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FOREWORD 


OBJECTIVE This guide describes the features and opera¬ 
tion of the Graphics Environment 

Manager..(GEM..) Virtual Device Interface 
(VDI), the successor to the Digital 
Research..Graphics System Extension (GSX..). 
You can write graphics applications using GEM 
VDI capabilities. 


AUDIENCE This guide is intended for microcomputer ap¬ 

plication programmers with operating system 
and graphics programming experience. 


ORGANIZATION This guide contains nine sections, ten appen¬ 

dixes, a glossary, and an index. The detach¬ 
able reference card at the end of this guide 
lists the GEM VDI functions by opcode number 
and gives their respective C binding proce¬ 
dure names. It also lists the section of 
this guide in which each function is dis¬ 
cussed. 

Section 1 introduces GEM VDI. It describes 
the GEM VDI architecture, including the 
Graphics Device Operating System (GDOS) and 
the device drivers. 

Section 2 describes GEM VDI operating proce¬ 
dures and how to integrate application 
programs with GEM VDI. 

Section 3 describes the control functions, 
which initialize the graphics workstation 
and set defaults for use with the applica¬ 
tion. 

Section 4 describes the output functions, 
which cause graphics primitives to be dis¬ 
played on a graphics output device (a screen 
or plotter, for example). 

Section 5 describes the attribute functions, 
which determine qualities of all subsequent 
output primitives, such as color and style. 

Section 6 describes the raster functions, 
which perform logic operations on raster 
areas (rectangular blocks of bits in memory 
or pixels on physical devices). 
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Section 7 describes the input functions, 
which allow the user to interact with the ap¬ 
plication program. 

Section 8 describes the inquire functions, 
which return the current settings for 
device-specific attributes, such as the num¬ 
ber of text styles supported. 

Section 9 describes the escape functions, 
which allow the application program to ac¬ 
cess special device capabilities. 

Appendix A lists and describes the GEM VDI 
error messages. 

Appendix B explains the ASSIGN.SYS file con¬ 
tents, which include information the GDOS 
uses to identify the output device. 

Appendix C lists and describes the GEM VDI 
metafile format. 

Appendix D defines the GEM VDI standard 
keyboard. 

Appendix E describes the mapping of GEM VDI 
to specific operating systems and the calling 
procedures needed to perform that mapping. 

Appendix F includes the system fonts. 

Appendix G describes the font file format. 

Appendix H describes the reserved metafile 
sub-opcodes. 

Appendix I describes the bit image file for¬ 
mat . 

Appendix J describes GDOS. 
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Section 1 
OVERVIEW 


INTRODUCTION The GEM VDI provides a device-independent en¬ 

vironment in which you can write graphics 
applications. This section describes GEM VDI 
and its architecture. Subsequent sections 
describe writing an application and all the 
GEM VDI functions. 


FEATURES The following features of GEM VDI make it 

possible for you to write graphics ap¬ 
plications that run under several microcom¬ 
puter operating systems: 


o GEM VDI provides a common graphics program¬ 
ming interface that is compatible with the 
most widely used operating systems, thus 
making it easy to port many programs. 

o GEM VDI provides a device-independent 
software interface for your application 
programs. You do not need to rewrite ap¬ 
plications for use with different output 
devices such as screens, printers, and 
plotters. GEM VDI handles device dif¬ 
ferences and makes it possible for you to 
send information to the devices through 
the application program as if the devices 
were the same. GEM VDI handles graphics 
requests and supplies the right driver to 
run the specific device. 


ENHANCEMENTS GEM VDI includes enhancements to GSX 

functions and now includes the following 
capabilities: 


o raster functions--functions that affect 
raster areas, which are rectangular blocks 
of pixels on physical devices or rectan¬ 
gular blocks of bits in memory 

o faces--letter styles stored in dynamically 
loadable files 
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ARCHITECTURE 


GEM VDI provides graphics primitives for im¬ 
plementing graphics applications with 
reduced programming effort- Application 
programs interface to GEM VDI through a 
standard calling sequence. Drivers for 
specific graphics devices translate the 
standard GEM VDI calls to the unique charac¬ 
teristics of each device. In this way, GEM 
VDI provides device independence. 

GEM VDI is composed of two components: 

o Graphics Device Operating System (GDOS) 
o device drivers and face files 

The GDOS contains the device-independent 
graphics functions, while the device drivers 
and face files contain the device-dependent 
code. 

GEM VDI is designed in this way to make the 
principal parts of the GDOS transportable to 
different hardware configurations. This 
design also allows applications to run in¬ 
dependently of the specific devices con¬ 
nected to the system. 


Graphics 

Device Operating 
System (GDOS) 


The GDOS performs coordinate scaling so that 
your application can specify points in a 
normalized space. It uses device-specific 
information to transform (map) the coor¬ 
dinates into the corresponding values for a 
particular graphics device. 

An application can also specify points in 
raster coordinate space, in which case no 
transformation occurs. 


The Graphics Device Operating System (GDOS) 
contains the basic host and device¬ 
independent graphics functions that can be 
called by your application program. GDOS 
provides a standard graphics interface that 
is constant regardless of specific devices 
or host hardware, just as the disk operating 
system standardizes disk interfaces. Your 
application program accesses the GDOS in 
much the same way that it accesses the 
operating system. 
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Architecture 


Graphics The graphics device drivers are similar to 

Device Drivers any I/O system. They contain the device¬ 

specific code required to interface your 
particular graphics devices to the GDOS. The 
device drivers communicate directly with the 
graphics devices. GEM VDI requires a unique 
device driver for each graphics device in a 
system. 

A single program can use several graphics 
devices; the GDOS loads only the appropriate 
device driver file into memory. By referring 
to devices with a device identification num¬ 
ber, an application program can send graphics 
information to any one of several memory- 
resident device drivers. 

The device driver outputs the GEM VDI 
graphics primitives according to the in¬ 
herent capabilities of a particular graphics 
device. In some cases, a device driver 
emulates standard capabilities not provided 
by the graphics device hardware. For ex¬ 
ample, some devices require that dashed lines 
be simulated by a series of short vectors 
generated in the device driver. 

The GEM VDI package contains drivers for many 
of the most popular microcomputer-related 
graphics devices. 


DEVICE TYPES You can write a GEM VDI-based graphics ap¬ 

plication for a variety of devices including 
screens, plotters, printers, and special 
cameras. 


Metafiles A metafile is the stored generic form of a 

picture file. Any application can create a 
GEM VDI metafile that can later be called 
into another graphics application. The 
metafile driver stores a description of a 
picture in a data file. These files can 
later be sent to any device or used to ex¬ 
change a picture between two applications. 
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Device Types 



When GEM VDI creates a metafile, it provides 
the ideal device. Raster Coordinate (RC) 
and Normalized Device Coordinate (NDC) space 
are the same (0 to 32767). No transform is 
applied. Refer to "Transforming Points" 
later in this section for more information on 
the coordinate spaces. 


Refer to Appendix C for information about the 
file format for metafiles. 

Multiple 

Workstations 

The application program specifies the 
graphics function to be performed by a 
device driver with an operation code (opcode) 
in the control array. "Opcodes” in Section 
2 describes the opcodes. 


Because multiple workstations can be open at 
the same time, each GEM VDI function must be 
provided with a unique reference to the 
desired device. This identification is 
referred to as the device handle. 

Device Handles 

The GDOS assigns the device handle when the 
Open Workstation function is called by the 
application program. The Open Workstation 
call returns the device handle in the array 
element contrl(6). All subsequent GEM VDI 
calls need to supply the device handle as an 
input in element contrl(6). 

ASSIGN.SYS 

The ASSIGN.SYS file is a text file, and can 
be created or edited using any text editor. 
The file lists the device driver filenames 
and face filenames, their device numbers, and 
device-specific information. The device num¬ 
bers are assigned according to their type. 
Refer to Table 1-1 for device numbers. 
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Table 1-1. Device Identification Numbers 
Device Type Device Number 


Screen 

1-10 

Plotter 

11-20 

Printer 

21-30 

Metafile 

31-40 

Camera 

41-50 

Tablet 

51-60 


APPLICATION With appropriate calls to the GDOS, you can 

PROGRAMS write application programs in assembly lan¬ 

guage or in a high-level language that sup¬ 
ports the GEM VDI calling conventions. You 
can compile or assemble and link programs 
containing GEM VDI calls in the normal man¬ 
ner. Refer to Section 2 for more informa¬ 
tion about writing graphics application 
programs. 


VIRTUAL DEVICE This guide contains the specification of the 
INTERFACE GEM Virtual Device Interface (VDI) and 

defines how applications interface to GEM 
VDI. The GEM VDI specifies the calling se¬ 
quence to access device driver functions as 
well as the necessary calling parameters. 
Refer to Appendix E for the main entry into 
the VDI for your operating system. 

The main entry point into the VDI is a single 
subroutine with five arguments, in the form 
of five arrays: 


o control array 
o array of input parameters 
o array of input point coordinates 
o array of output parameters 
o array of output point coordinates 
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Virtual Device Interface 


All array elements are of type INTEGER (2 
bytes). All arrays are zero-based; that is, 
the double-word address of the Parameter 
Block (PB) points to the first element of 
the control array, contrl(O). The content of 
the input and output parameter arrays 
depends on the opcode. Refer to Section 2 
for more information about writing graphics 
applications. 


TRANSFORMING All computer graphics are displayed using a 
POINTS coordinate system. GEM VDI makes sure the 

coordinate system of one device matches the 
coordinate system of another. For example, 
with GEM VDI, the application program 
produces the same graphics image on a printer 
as on a screen. The linetypes and fill 
styles are the same in Normalized Device 
Coordinates (NDC), which are described below. 
Character sizes are different. The same 
number of characters are displayed per line, 
but a printer's line length is generally 
greater than a screen 1 s. 


Transformation The application program can address the 

Mode display surface using one of two coordinate 

systems: 

o Normalized Device Coordinates (NDC) 
o Raster Coordinates (RC) 

The transformation mode, specified at Open 
Workstation, determines which coordinate sys¬ 
tem is used. 


Normalized Device Normalized Device Coordinates (NDC) address 
Coordinates the graphics display independent of the 

device coordinate size. These units are then 
mapped to Raster Coordinates by the GDOS. 
The transformation mode set at Open Worksta¬ 
tion determines whether the GDOS maps from 
NDC units to the Raster Coordinates. 
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The full scale of NDC space (0-32767) is 
mapped to the full dimensions of the device 
on both axes. On a nonsquare display with 
square pixels, a different scale factor is 
applied to each axis with this transformation 
mode. 

NDC space has its origin at the lower left 
corner, and its (xmax,ymax) point at the up¬ 
per right corner. This space is in the first 
quadrant of the Cartesian coordinate system. 

When transforming from NDC to Raster Coor¬ 
dinates (RC), the GDOS assumes a raster 
coordinate at the bottom left edge of a 
pixel. You should compensate for a boundary 
condition created at the top edge of NDC 
space. 

This problem is best illustrated with an ex¬ 
ample. Given the display of Figure 1-1 in 
Transformation Mode 0, the NDC point 
(32767,32767) maps to the point (0,200) in 
RCs. But because pixels are addressed at 
their lower left corner, the NDC point 
(32766,32766) maps to the point (1,199) in 
RCs. The application programmer should cor¬ 
rect for this boundary error by adding half 
of the NDC height and width into the coor¬ 
dinate transform to ensure that any roundoff 
error in the application-world-to-NDC trans¬ 
form does not cause the wrong pixel to be 
addressed. 


Raster Coordinates Raster Coordinates (RC) are actual device 

units (for example, rasters for screens or 
steps for plotters and printers). Unlike 
NDCs, RCs have their origin at the upper 
left corner, and the (xmax,ymax) point at the 
bottom right pixel of the space. Refer to 
Figure 1-1 for an illustration of this con¬ 
cept. 

No transformation occurs when the RC system 
is in effect. The application needs to ad¬ 
just its transform based on the aspect ratio 
of pixels on the screen. The raster coor¬ 
dinate system saves the overhead of the GDOS 
having to perform a transformation on every 
point. 


1-7 



GEM VDI Programmer's Guide 


Transforming Points 



Figure 1-1. Transformation Modes 


End of Section 1 
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Section 2 

WRITING A GRAPHICS APPLICATION 


INTRODUCTION 


WRITING THE 
PROGRAM 


This section explains how to use GEM VDI in 
your graphics applications. 


You can write your graphics application in 
one of two ways: 


o using assembly language 

o using high-level language bindings (C lan¬ 
guage bindings are provided.) 


The first method addresses functions by their 
opcode numbers, the second by procedure name. 
The C Language bindings provided for each 
function allow for portability across im¬ 
plementations. In the C bindings, which ap¬ 
pear with each function in sections 3 through 
9, WORD declares a 16-bit integer type; BYTE 
declares an 8-bit integer type. 

The following figure is produced by the 
sample C language graphics application in 
Listing 2-1 that follows the figure. 
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Figure 2-1. Output from the Sample Program 


Listing 2-1. Sample Program 

/* This program draws an ellipse that is centered */ 

/* on the output device, whose radii are 1/2 the */ 

/* x and y resolutions */ 

tinclude <osbind.h> 

tdefine HIDE_MOUSE graf_mouse(256,Sdummy) 
tdefine SHOW_MOUSE graf_mouse(257,&dummy) 

/* these globals are required for the operation */ 

/* of the VDI */ 

int contrl[12], intin[256], ptsin[256], intout[256], ptsout[256]; 

main( ) 

{ 

int work_in[ll],work_out[57]; 
int handle, i, dummy; 
int charw, charh, boxw, boxh; 
int xres,yres; 

/* Set the system up to do GEM calls*/ 
appl_init(); 

/* Get the handle of the desktop */ 

handle=graf_handle(&charw,Scharh,&boxw,&boxh); 

/* Open the workstation. */ 
work_in[0]=Getrez()+2; 
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for (i=l; i<10; ++i) work_in[i] = 1; 
work_in[10] = 2;/* Use RC corrdinates */ 
v_opnvwk(work_in, ^handle, work_out); 

xres=work_out[0]; 
yres=work_out[1]; 

HIDE_MOUSE; 

v_clrwk(handle); 

v_ellipse(handle,xres/2,yres/2,xres/4,yres/4); 
evnt_keybd(); 

SHOW_MOUSE; 

/* Close the workstation. */ 
v_clsvwk(handle); 

/* Release GEM calls */ 

appl_exit(); 


} 


GEM VDI Functions The functions are grouped by type, output, 

and so on. Each device type requires cer¬ 
tain functions, lists of which follow. 


Opcodes Opcodes are numbers assigned to each GEM VDI 

function. The device drivers recognize all 
opcodes, whether or not they produce any 
action. If an opcode is out of range, the 
driver performs no action. 


Required Functions Screens require the following functions and 
for Screens subfunctions: 


Opcode Definition 


1 Open workstation 

2 Close workstation 

3 Clear workstation 

4 Update workstation 

5 Escape 
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6 

7 

8 
9 

11 


12 

14 

15 

17 

18 
20 
21 
22 

23 

24 

25 

26 
28 

31 

32 


id Definition 

1 Inquire addressable character 
cells 

2 Exit alpha mode 

3 Enter alpha mode 

4 Cursor up 

5 Cursor down 

6 Cursor right 

7 Cursor left 

8 Home cursor 

9 Erase to end of screen 

10 Erase to end of line 

11 Direct cursor address 

12 Output cursor addressable text 

15 Inquire current alpha cursor 

address 

18 Place graphic cursor 

19 Remove last graphic cursor 

Polyline 

Polymarker 

Text 

Filled area 

Generalized Drawing Primitive (GDP) 
id Definition 

1 Bar 

2 Arc 

3 Pie 

4 Circle 

5 Ellipse 

6 Elliptical Arc 

7 Elliptical Pie 

8 Rounded rectangle 

9 Filled rounded rectangle 

10 Justified graphics text 

Set character height absolute mode 

Set color representation 

Set polyline linetype 

Set polyline color index 

Set polymarker type 

Set polymarker color index 

Set text face 

Set text color index 

Set fill interior style 

Set fill style index 

Set fill color index 

Inquire color representation 

Input locator 

Input string 

Set writing mode 
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33 Set input mode 

35 Inquire current polyline attributes 

36 Inquire current polymarker 

attributes 

37 Inquire current fill area attributes 

38 Inquire current graphic text 

attributes 

39 Set graphic text alignment 

100 Open virtual screen workstation 

101 Close virtual screen workstation 

102 Extended inquire function 

104 Set fill perimeter visibility 

106 Set graphic text special effects 

107 Set character cell height, points 
mode 

108 Set polyline and styles 

109 Copy raster, opaque 

110 Transform form 

111 Set mouse form 

112 Set user-defined fill pattern 

113 Set user-defined linestyle 

114 Fill rectangle 

115 Inquire input mode 

116 Inquire text extent 

117 Inquire character cell width 

118 Exchange timer interrupt vector 

121 Copy raster, transparent 

122 Show cursor 

123 Hide cursor 

124 Sample mouse button state 

125 Exchange button change vector 

126 Exchange mouse movement vector 

127 Exchange cursor change vector 

128 Sample keyboard state information 

129 Set clipping rectangle 

130 Inquire face name and index 

131 Inquire current face information 


Required Functions Printers require the following functions and 
for Printers subfunctions: 


Opcode 


Definition 


1 Open workstation 

2 Close workstation 

3 Clear workstation 

4 Update workstation 

5 Escape 
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6 

7 

8 
9 

11 


12 

15 

17 

18 
20 
21 
22 

23 

24 

25 

26 
32 

35 

36 

37 

38 

39 
102 
104 
106 

107 

108 
112 
116 
117 


id Definition 

1 Inquire addressable character 
cells 

20 Form advance 

21 Output window 

22 Clear display list 

23 Output bit image file 
Polyline 

Polymarker 

Text 

Filled area 

Generalized Drawing Primitive (GDP) 
id Definition 

1 Bar 

2 Arc 

3 Pie 

4 Circle 

5 Ellipse 

6 Elliptical Arc 

7 Elliptical Pie 

8 Rounded rectangle 

9 Filled rounded rectangle 

10 Justified graphics text 

Set character height absolute mode 

Set polyline linetype 

Set polyline color index 

Set polymarker type 

Set polymarker color index 

Set text face 

Set text color index 

Set fill interior style 

Set fill style index 

Set fill color index 

Inquire color representation 

Set writing mode 

Inquire current polyline attributes 
Inquire current polymarker 
attributes 

Inquire current fill area attributes 
Inquire current graphic text 
attributes 

Set graphic text alignment 
Extended inquire function 
Set fill perimeter visibility 
Set graphic text special effects 
Set character height points mode 
Set polyline end styles 
Exchange fill pattern 
Inquire text extent 
Inquire character cell width 
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129 Set clipping 

130 Inquire face name and index 

131 Inquire current face information 


Required Functions Plotters require the following functions and 
for Plotters subfunctions: 

Opcode Definition 

1 Open workstation 

2 Close workstation 

3 Clear workstation 

4 Update workstation 

5 Escape 

id Definition 

1 Inquire addressable character 
cells 


6 Polyline 

7 Polymarker 

8 Text 

9 Filled area 

11 Generalized Drawing Primitive (GDP) 

id Definition 

1 Bar 

2 Arc 

3 Pie 

4 Circle 

5 Ellipse 

6 Elliptical arc 

7 Elliptical pie 

8 Rounded rectangle 

9 Filled rounded rectangle 

10 Justified graphics text 

12 Set character height absolute mode 

15 Set polyline linetype 

17 Set polyline color index 

18 Set polymarker type 

20 Set polymarker color index 

21 Set text face 

22 Set text color index 

23 Set fill interior style 

24 Set fill style index 

25 Set fill color index 

35 Inquire current polyline attributes 

36 Inquire current polymarker 
attributes 
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37 Inquire current fill area attributes 

38 Inquire current graphic text 
attributes 

39 Set graphic text alignment 

102 Extended inquire function 

104 Set fill perimeter visibility 

107 Set character height points mode 

108 Set polyline end styles 

116 Inquire text extent 

117 Inquire character cell width 

124 Set clipping 

130 Inquire face name and index 

131 Inquire current face information 


Required Functions Because metafiles are transportable to any 
for Metafiles device, the required functions are all those 

common to any device you may use. Metafiles 
support some inquiries by returning the op¬ 
code number. Refer to Appendix C for the 
metafile format of those supported inquires. 

Metafiles require the following functions and 
subfunctions: 


Opcode Definition 

1 Open workstation 

2 Close workstation 

3 Clear workstation 

4 Update workstation 

5 Escape 

id Definition 

1 Inquire addressable character 
cells 

2 Exit'alpha mode 

3 Enter alpha mode 

20 Form advance 

21 Output window 

22 Clear display list 

23 Output bit image file 

98 Update metafile extents 

99 Write metafile item 

100 Change GEM VDI filename 
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6 Polyline 

7 Polymarker 

8 Text 

9 Filled area 

11 Generalized Drawing Primitive (GDP) 

id Definition 

1 Bar 

2 Arc 

3 Pie 

4 Circle 

5 Ellipse 

6 Elliptical arc 

7 Elliptical pie 

8 Rounded rectangle 

9 Filled rounded rectangle 

10 Justified graphics text 

12 Set character height absolute mode 

13 Set character baseline vector 

14 Set color representation 

15 Set polyline linetype 

16 Set polyline line width 

17 Set polyline color index 

18 Set polymarker type 

19 Set polymarker height 

20 Set polymarker color index 

21 Set text face 

22 Set text color index 

23 Set fill interior style 

24 Set fill style index 

25 Set fill color index 

26 Inquire color representation 

32 Set writing mode 

35 Inquire current polyline attributes 

36 Inquire current polymarker 
attributes 

37 Inquire current fill area attributes 

38 Inquire current graphic text 

attributes 

39 Set graphic text alignment 

102 Extended inquire function 

103 Contour fill 

104 Set fill perimeter visibility 

106 Set graphic text special effects 

107 Set character height points mode 

108 Set polyline end styles 

112 Set fill pattern 

113 Set user-defined line style pattern 

114 Fill rectangle 

117 Inquire character cell width 
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129 Set clipping rectangle 

131 Inquire current face information 
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Available 

Opcodes 

You can determine if a function is available 
in a specific driver in one of the following 
ways: 


o Check the information about available 

features returned from the Open Worksta¬ 

tion function or the Extended Inquire func¬ 
tion. 


o Check the selected value returned from an 
opcode against the requested value. If the 
two values are not the same, then either 
the function is not available or the re¬ 
quested value is not available, and GEM VDI 
selected a best fit value. 

Format 

The following is the format for the 

parameters for all GEM VDI functions. 


Input Parameters contrl(O) -- Opcode number for the GEM 

VDI function. 

contrl(l) -- Number of vertices in the 

ptsin array. 

Each vertex consists of an 
x,y coordinate pair, so the 
length of the ptsin array 
is twice the number of 
specified vertices 

contrl(3) — Length of integer array in¬ 

tin. 

contrl(5) — Subfunction identification 

number for a Generalized 
Drawing Primitive (GDP) or 
Escape. 

contrl(6) — Device handle. 

contrl(7-n) — Opcode-dependent informa¬ 

tion. 

intin — Array of integer input 

parameters. 

ptsin — Array of input point coor¬ 

dinate data. 
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Output Parameters 


CALLING 

CONVENTIONS 


Refer to the Extended 
Inquire function in Section 
8 for information on how to 
determine the maximum size 
for the ptsin array. 


contrl(2) 


contrl(4) 

contrl(6) 
contrl(7-n) 


Number of vertices in the 
ptsout array. 

Each vertex consists of an 
x,y coordinate pair, so the 
length of the ptsout array 
is twice the number of 
specified vertices. 

Length of integer array in¬ 
tout. 

Device handle. 

Opcode-dependent informa¬ 

tion. 


intout — Array of integer output 

point parameters. 

ptsout — Array of output point coor¬ 

dinate data. 


Because both input and output coordinates 
may be converted by the GDOS, the calling 
routine must ensure that the vertex count, 
contrl(l), is set correctly. Contrl(l) must 
be set to 0 if no x,y coordinates are being 
passed to GEM VDI by the application program. 
In addition, the input integer count, con- 
trl(3), must always be set. The calling 
routine must set contrl(3) to 0 if no in¬ 
tegers are being passed to GEM VDI. 
Similarly, contrl(2), the output vertex 
count, and contrl(4), the output integer 
count, are always set correctly by GEM VDI. 
These values contain zeros if no information 
is being passed back in ptsout and intout, 
respectively. 

The double-word addresses of the five 
parameter arrays are stored in a ten-word 
data structure referred to as a Parameter 
Block (PB). 
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Registers and 
Interrupts 


RUNNING GRAPHICS 
APPLICATIONS 
UNDER GEM VDI 


Refer to Appendix E for the specific 
registers and interrupts for various 
operating systems. 


Table 

2-1. Parameter Block Contents 

Address 

Contents 

PB 

control array (contrl) 

PB + 4 

input parameter array (intin) 

PB + 8 

input point coordinate 
array (ptsin) 

PB + 12 

output parameter array (intout) 

PB + 16 

output point coordinate 
array (ptsout) 


To use the graphics features provided by 
GEM VDI, you must ensure that the following 
conditions are met: 


1. Your application program must conform to 
the GEM VDI calling convention to access 
graphics primitives. This process invol¬ 
ves the application making a call to the 
GDOS and using the interrupt for your 
operating system. Refer to Appendix E for 
the specific interrupts. 

The parameter list provides information 
to GEM VDI and returns information to the 
calling program. The details of 

parameter passing are in the previous sec¬ 
tion. 

2. Enough stack space must be available for 
GEM VDI operations. This space includes 
a buffer area for transforming points 
passed to GEM VDI and some fixed overhead 
space. The formula to determine the re¬ 
quired stack space is discussed under 
"Determining Memory Requirements" later in 
this section. 
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3. When your program is executed, the re¬ 
quired device drivers must be present on 
the disk specified in the GEM VDI 
graphics-mode command, or in the current 
default drive if no drive is specified. 
The ASSIGN.SYS file must contain the 
names of your device drivers and a device 
ID number for each device driver. Refer 
to "ASSIGN.SYS" in Section 1 for informa¬ 
tion about creating an ASSIGN.SYS file. 

4. After successfully compiling or assembling 
and linking your application program, you 
can run it like any program, once GEM VDI 
is active. You can enable GEM VDI 
graphics with the GEMVDI graphics-mode 
command, described under "Enabling 
Graphics" below. 


ENABLING GRAPHICS Special commands let you enable graphics 

functions from the command level of the 
operating system. 

To load GEM VDI and start a non-GEM applica¬ 
tion that uses the VDI (like a test program 
or debugger), type the following command: 

GEMVDI /FILENAME 

To load GEM VDI and start a GEM application, 
type the following command: 

GEMVDI FILENAME 

To load GEM VDI and start the GEM Desktop.. 
application, type the following command: 

GEMVDI 

Each command loads GDOS and any drivers 
declared resident in the ASSIGN.SYS file. 
ASSIGN.SYS and the driver files must be 
located in one of the directories in the 
current search path. 


2-14 




GEM VDI Programmer's Guide 


Enabling Graphics 


Any application to be invoked by a GEMVDI 
command must also be located in the search 
path. 


DISABLING GRAPHICS When the application invoked by the GEMVDI 

command terminates, GEM VDI relinquishes all 
system memory space, leaving the maximum 
memory for nongraphics programs. 


DETERMINING MEMORY To determine the amount of stack space 
REQUIREMENTS required to run a given application, make the 

following calculation: 


Open workstation call = approximately 128 

bytes 

All other calls = ptsin size + 128 bytes + 

the overhead requirements 
of the operating system 


Ptsin is the point array passed to the device 
driver from the application program (two 
words for each point). 

The stack requirement is the larger of the 
two resulting values. This stack space must 
be available in the application program stack 
area. 

GEM VDI requires less than 30 kilobytes in 
memory for a single open driver. This space 
is allocated when you enter the GEM VDI 
graphics-mode command. 


DEBUGGING GRAPHICS 
APPLICATIONS 
UNDER GEM VDI 


Graphics programs can be debugged with a 
debugging tool. The default device drivers 
and GDOS are loaded after you enter the 
GEMVDI command. Your graphics application 
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program is loaded in the normal manner for 
programs on your operating system. 


End of Section 2 
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INTRODUCTION 

The control functions initialize the graphics 
workstation and set defaults for use with the 
application. 

OPEN WORKSTATION 

The Open Workstation function loads a 
graphics device driver for the application 
program and returns a device handle. The 
device is initialized with the parameters in 
the input array. Information about the 
device is returned; additional device¬ 
specific information is returned in the 
Extended Inquire function. 


If the device is a screen, it is initialized 
to graphics mode. GEM VDI clears the display 
surface. 


If the device cannot be opened, GEM VDI 
returns a zero as the device handle in con¬ 
trl (6). Any nonzero value in contrl(6) in¬ 
dicates a successful operation. 


Input contrl(O) -- 

contrl(1) — 
contrl(3) — 

intin 


intin(O) 


intin(1) 
intin(2) 
intin(3) 
intin(4) 
intin(5) 
intin(6) 
intin(7) 
intin(8) 
intin(9) 


Opcode = 1. 

Number of input vertices = 0. 
Length of intin array = 11. 

Initial defaults (for example, 
linestyle, color, character 
size). 

Device id number. 

This value determines which 
device driver to dynamically 
load in memory. 

Linetype. 

Polyline color index. 

Marker type. 

Polymarker color index. 

Text face. 

Text color index. 

Fill interior style. 

Fill style index. 

Fill color index. 
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intin(lO) — NDC to RC transformation flag. 

0 = Map the full NDC space to 
the full RC space. 

1 = Reserved. 

2 = Use the RC system. 


Output contrl(2) -- Number of output vertices = 6. 

contrl(4) -- Length of intout array = 45. 

contrl(6) — Device handle for this device. 

intout(O) -- Maximum addressable width of 
screen or plotter in rasters 
or steps, assuming a 0 start 
point (for example, a resolu¬ 
tion of 640 implies an ad¬ 
dressable area of 0-639, so 
intout(0)=639). 

intout(l) -- Maximum addressable height of 
screen or plotter in rasters 
or steps, assuming a 0 start 
point (for example, a resolu¬ 
tion of 480 implies an ad¬ 
dressable area of 0-479, so 
intout(1)=479). 

intout(2) — Device Coordinate units flag. 

0 = Device capable of 

producing precisely 

scaled image (typically 
a plotter or a printer). 

1 = Device not capable of 
producing precisely 

scaled image (typically a 
film recorder). 

intout(3) — Width of one pixel (plotter 
step, or aspect ratio for 
screen) in microns. 

intout(4) -- Height of one pixel (plotter 
step, or aspect ratio for 
screen) in microns. 

intout(5) — Number of character heights. 

0 = Continuous scaling. 

intout(6) -- Number of linetypes. 

intout(7) -- Number of line widths. 

0 = Continuous scaling. 
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intout(8) 
intout(9) 


intout(10) 


intout(11) 
intout(12) 
intout(13) 


intout(14) 

intout(15) 
intout(24) 


intout(25) 
intout(34) 


intout(35) 


Number of marker types. 

Number of marker sizes. 

0 = Continuous scaling. 

Number of faces supported 
by device (not the highest 
numbered face index). 

Number of patterns. 

Number of hatch styles. 

Number of predefined colors (2 
for monochrome devices). 

This is the number of colors 
that can be displayed on the 
device simultaneously. 

Number of Generalized Drawing 
Primitives (GDPs). 
to 

Linear list of the first ten 
supported GDPs. 

The number indicates which 
GDP is supported. A -1 in¬ 
dicates the end of the list of 
supported GDPs. GEM VDI 

defines ten GDPs. 

1 — Bar 

2 — Arc 

3 — Pie slice 

4 -- Circle 

5 -- Ellipse 

6 — Elliptical arc 

7 — Elliptical pie 

8 — Rounded rectangle 

9 -- Filled rounded rectangle 

10 -- Justified graphics text 

to 

Linear list of attribute set 
associated with each GDP. 

0 -- Polyline 

1 — Polymarker 

2 — Text 

3 — Fill area 

4 -- None 

Color capability flag. 
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0 — No 
1 -- Yes 

intout(36) -- Text rotation capability flag. 

0 — No 
1 — Yes 

intout(37) -- Fill area capability flag. 

0 — No 
1 — Yes 

intout(38) — Cell array operation 

capability flag. 

0 -- No 

1 -- Yes 

intout(39) — Number of available colors 
(total number of colors in 
color palette). 

0 -- Continuous device 

(more than 32767 colors) 

2 — Monochrome (black and 

white) 

>2 -- Number of colors avail¬ 
able 

intout(40) — Number of locator devices 
available. 

1 -- Keyboard only 

2 — Devices with keyboard and 

other input 

intout(41) — Number of valuator devices 

available. 

1 -- Keyboard 

2 — If another valuator 
device is available 

intout(42) -- Number of choice devices 

available. 

1 — Function keys on keyboard 

2 — If another button pad is 

available 

intout(43) — Number of string devices 

available. 


3-4 


GEM VDI Programmer's Guide 


Open Workstation 


intout(44) 


ptsout(0) 
ptsout(1) 


ptsout(2) 
ptsout(3) 


ptsout(4) 


ptsout(5) 
ptsout(6) 


ptsout(7) 
ptsout(8) 


ptsout(9) 


1 — Keyboard 
Workstation type. 

0 — Output only 

1 — Input only 

2 -- Input/output 

3 — Reserved 

4 — Metafile output 

Minimum character width. 
Minimum character height in 
the y-axis in the current 
coordinate system. 

The minimum and maximum 
character heights are the ac¬ 
tual character body (baseline 
to top line), not the charac¬ 
ter extent box, which may in¬ 
clude extra space used for in¬ 
terline or intercharacter 
spacing. 

Maximum character width. 
Maximum character height in 
the y-axis in the current 
coordinate system. 

Minimum line width in the x- 
axis in current coordinate 
system. 

The minimum line width is a 
nominal device-dependent size. 
If the minimum line width used 
is 1 device unit, the line may 
not be visible on some high- 
resolution devices. 

0 . 

Maximum line width in the x- 
axis in the current coordinate 
system. 

0 . 

Minimum marker width in x-axis 
in the current coordinate sys¬ 
tem. 

Minimum marker height in x- 
axis in the current coordinate 
system. 
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Default 

Tables 


ptsout(lO) -- Maximum marker width in x-axis 
in the current coordinate sys¬ 
tem. 

ptsout(ll) -- Maximum marker height in x- 
axis in the current coordinate 
system. 


Color The default color table is set up differently 

for monochrome and color devices. 

Table 3-1. Monochrome Screens 

Index Color 

0 White 

1 Black 


Table 3-2. Monochrome Printer/Plotters 

Index Color 

0 White 

1 Black 


Table 3-3. Color Screens 


Index 


Color 


0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 
16-n 


White 

Black 

Red 

Green 

Blue 

Cyan 

Yellow 

Magenta 

White 

Black 

Light Red 

Light Green 

Light Blue 

Light Cyan 

Light Yellow 

Light Magenta 

Device-dependent 
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Other default values set by the driver during 
initialization are listed in Table 3-4. 


Table 3-4. 
Attribute 
Character height 

Character baseline 
rotation 

Text alignment 

Text style 

Line width 

Marker height 

Polyline end styles 

Writing mode 

Input mode 

Fill area perimeter 
visibility 

User-defined line 
style 

User-defined fill 
pattern 

Cursor 

Clipping 


Default Values 

Default Value 

Nominal character 
height 

0 degrees rotation 
Left baseline 
Normal intensity 
Nominal line width 
Nominal marker height 
Squared 
Replace 

Request for all input 
classes (locator, 
valuator, choice, 
string) 

Visible 

Solid 

Solid 

Hidden 

Disabled 
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C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


v_opnwk( work_in, Shandle, work_out ) 


WORD v_opnwk ( ); 
WORD work_in[ll]; 
WORD handle; 

WORD work out[57]; 


work_in[0] = intin[0] 
work in[l] = intin[l] 


work in[10] = intin[10] 


handle = contrl[6] 
work_out[0] = intout[0] 
work_out[1] = intout[1] 


work_out[44] = intout[44] 
work_out[45] = ptsout[0] 


work_out[56] = ptsout[ll] 
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CLOSE WORKSTATION The Close Workstation function terminates the 

graphics device properly (returning you to 
alpha mode) and prevents any further output 
to the device. If the device is a screen, 
the alpha device is selected, and the 
graphics device is deselected. If the 
device is a printer, an update occurs if one 
has not just taken place. For a metafile, 
GEM VDI flushes the buffer and closes the 
metafile. 

Note: Close your open virtual workstations 

before closing the workstation. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 2. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 


Output 


contrl(2) — Length of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_clswk( handle ) 

WORD vclswk ( ); 

WORD handle; 

handle = contrl[6] 
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OPEN VIRTUAL This function allows a single physical screen 

SCREEN WORKSTATION to act as multiple workstations. Each 

workstation has access to the entire screen. 

However, attribute environments for each 
workstation are maintained separately. For 
example, the workstation may have different 
transformation modes, clipping rectangles, 
and so on. 

Note: Not all input devices associated with 
the virtual workstation will work. 

The input to the Open Virtual Screen Worksta¬ 
tion function is the device handle of a cur¬ 
rently open physical screen workstation and 
an environment initialization array (see 
"Open Workstation"). If the virtual screen 
workstation can be opened, a new device 
handle is returned for the virtual worksta¬ 
tion. The device capabilities arrays for the 
physical screen workstations are returned as 
they are for the Open Workstation function. 
If the virtual screen workstation cannot be 
opened, a zero is returned as the device 
handle to indicate an unsuccessful request. 


Input contrl(O) — Opcode = 100. 

contrl(l) — Number of input vertices = 0. 
contrl(3) -- Length of intin = 11. 

contrl(6) -- Device handle of a previously 

opened screen device. 

intin — For a description of the intin 

parameters required in the in¬ 
tin array see Open Worksta¬ 
tion (Opcode 1). 
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Output 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


contrl(2) 
contr1(4) 
contrl(6) 


Warning: 


Note: 


Number of output vertices = 6. 
Length of intout = 45. 

The device handle for the Vir¬ 
tual Screen Device just 
opened. 

Contrl(6) is an input/output 
parameter. The value is 
changed to that of the Virtual 
Screen Workstation device 
handle. 

All output parameters are the 
same as those of Open Worksta¬ 
tion (Opcode 1). 


v_opnvwk( work_in, &handle, work_out ) 


WORD vopnvwk( ); 

WORD handle; 

WORD work_in[11]; 
WORD work out[57]; 


handle = contrl[6] 
work in[0] = intin[0] 


work in[10] = intin[10] 


work_out[0] 

work_out[44] 
work_out[45] 

work out[56] 


= intout[0] 

= intout[44] 
= ptsout[0] 

= ptsout[ll] 
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Close Virtual Screen Workstation 


CLOSE VIRTUAL 

SCREEN WORKSTATION 

The Close Virtual Screen Workstation function 
terminates the virtual device and prevents 
any further output to it. 

Input 

contrl(O) -- 
contrl (1) — 
contrl(3) -- 
contrl(6) — 

Opcode 

Number 

Length 

Device 

= 101. 

of input vertices = 0. 
of intin = 0. 
handle. 

Output 

contrl ( 2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout = 0. 


C BINDING 

Procedure Name v_clsvwk( handle ) 

Data Types WORD v_clsvwk( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Clear Workstation 


CLEAR WORKSTATION 

The Clear Workstation function erases the 
screen- GEM VDI sets the screen to the cur¬ 
rently selected background color, which is 
defined as color index zero. If the device 
is a plotter without paper advance, GEM VDI 
prompts the operator to load a new page. If 
the device is a printer, data in the buffer 
is erased and a new page occurs. For a 
metafile, GEM VDI outputs the opcode. No 
output occurs for any device. 


Note: With GEM VDI, you do not need to do a 
Clear Workstation after an Open Workstation 
because the display is cleared at Open 
Workstation. 

Input 

contrl(O) -- 
contrl(1) — 
contrl(3) — 
contrl(6) — 

Opcode = 3. 

Number of input vertices = 0. 
Length of intin = 0. 

Device handle. 

Output 

contrl(2) — 
contrl(4) -- 

Number of output vertices = 0. 
Length of intout = 0. 


C BINDING 
Procedure Name 

Data Types 


v_clrwk( handle ) 

WORD v_clrwk ( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Update Workstation 


UPDATE WORKSTATION The Update Workstation function causes all 

pending graphics commands to be executed im¬ 
mediately, in the order the commands were 
stored in the buffer. For printer drivers, 
you must use this function to start output to 
the printer. This function has no effect on 
screens. Plotters execute all the commands 
in the buffer. When the plotter buffer is 
empty, it returns from the Update Workstation 
function. For a metafile, GEM VDI outputs 
the opcode. 

Note: The picture is drawn to the printer 
but no new page occurs. A Clear Workstation 
causes a new page. 


Input 


contrl(O) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 4. 

Number of input vertices = 0. 
Length of intin = 0. 

Device handle. 


Output 


contrl(2) — Number in output vertices = 0. 

contrl(4) — Length of intout = 0. 


C BINDING 

Procedure Name v_updwk( handle ) 

Data Types WORD v_updwk ( ); 

WORD handle; 

Input Arguments handle = contrl[6] 
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LOAD FONTS 


This function loads the fonts associated with 
a particular driver in the ASSIGN.SYS file. 
It then makes them available to the ap¬ 
propriate program. 

GEM VDI returns the number of newly generated 
font identifiers. If the fonts were already 
available to the workstation, no action oc¬ 
curs, and GEM VDI returns a zero for the 
number of additional font identifiers. 

Note: You must have GDOS installed to make 

this call. See "How to tell if GDOS is in¬ 
stalled” in the GDOS Appendix. You do not 
need to invoke load_fonts if the default 
system fonts for a particular driver are suf¬ 
ficient. 


Input contrl(O) — Opcode = 119. 

contrl(l) — Number of input vertices = 0. 
contrl(3) — Length of intin array = 1. 
contrl(6) — Device handle. 

intin(O) -- Reserved for future use = 0. 


Output contrl(2) — Number of output vertices = 0. 

contrl(4) -- Length of output array = 1. 

intout(0) -- Number of additional font iden¬ 
tifiers . 


C BINDING 

Procedure Name additional = vst_load_fonts( handle, select ) 


Data Types WORD vst_load_fonts ( ); 

WORD handle; 

WORD select; 


Input Arguments handle = contrl[6] 

select = intinEO] 

Output Arguments additional = intout[0] 
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UNLOAD FONTS This function logically dissociates the ex¬ 

ternal fonts loaded by the Load Fonts func¬ 
tion from a device and unloads them from 
memory, if possible. A device handle is 
passed into the function identifying the 
device whose external fonts are to be un¬ 
loaded . 

If the fonts are being shared by other vir¬ 
tual workstations with the same root device 
handle, the fonts are not unloaded from 
memory until one of the following conditions 
is met: 

Note: If you build a page with fonts from 

the vst_load_fonts call you should make the 
update workstation call before unloading 
fonts since vst_unload_fonts will remove 
fonts from the device. 


o all workstations that share the fonts are 
closed 

o all workstations that share the external 
fonts request that the external fonts be 
unloaded 


The default system fonts for the workstation 
remain loaded and available. 


Input contrl(O) 

contrl(1) 
contrl(3) 
contrl(6) 

intin(O) 


Opcode = 120. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 

Reserved for future use. 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 0. 
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Unload Fonts 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


vst unload fonts( handle. 


WORD vst_unload_fonts( ); 
WORD handle; 

WORD select; 


handle = contrl[6] 
select = intin[0] 


select ) 
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Set Clipping Rectangle 


SET CLIPPING 
RECTANGLE 


Input 


This function enables or disables clipping of 
all output primitives by GEM VDI. Intin(O) 
is a flag, which if nonzero, enables clip¬ 
ping. The ptsin array contains the rec¬ 
tangle, specified in the current coordinate 
system, to clip to. If intin(O) is zero, 
clipping is turned off. The default at Open 
Workstation is for clipping to be disabled. 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 129. 

Number of input vertices = 2. 
Length of intin array = 1. 
Device handle. 


intin(O) 


ptsin(O) 


ptsin(1) 


ptsin(2) 


ptsin(3) 


Clipping flag. 

0 = Turn clipping off. 
non-zero = Turn clipping on. 

x-coordinate of corner of the 
clipping rectangle in NDC/RC 
units. 

y-coordinate of corner of the 
clipping rectangle in NDC/RC 
units. 

x-coordinate of corner diagon¬ 
ally across from the corner 
selected in ptsin(O) of the 
clipping rectangle in NDC/RC 
units. 

y-coordinate of corner diagon¬ 
ally across from the corner 
selected in ptsin(1) of the 
clipping rectangle in NDC/RC 
units. 
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Set Clipping Rectangle 


C BINDING 

Procedure Name 
Data Types 

Input Arguments 


vs_clip( handle, clip_flag, 
WORD vs_clip(); 

WORD handle; 

WORD clip_flag; 

WORD pxyarray[4]; 


handle = contrl[6] 
clip_flag = intin[0] 
pxyarray[0] = ptsin[0] 
pxyarray[l] = ptsin[l] 
pxyarray[2] = ptsin[2] 
pxyarray[3] = ptsin[3] 


pxyarray ) 


End of Section 3 
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Section 4 
OUTPUT FUNCTIONS 


INTRODUCTION 


POLYLINE 


The output functions display graphics 
primitives (polyline or circle, for example) 
on devices. 


This function displays a polyline on the 
graphics device. The starting point for the 
polyline is the first point in the input ar¬ 
ray. Lines are drawn between subsequent 
points in the array. GEM VDI displays a zero 
length line (degenerate case) as a point. 
GEM VDI will not display a single coordinate 
pair. Lines are drawn using the following 
current line attributes: 


o color 
o linetype 
o line width 
o end style 

o current writing mode 


For wide lines, the first point (ptsin(O), 
ptsin(l)) is drawn as shown in Figure 4-1. 


Figure 4-1. First Point for Wide Lines 
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Polyline 


Input 

contrl(0) — 
contrl(1) — 

Opcode = 6. 

Number of vertices (x,y pairs) 
in polyline = n. 



(Maximum number is returned in 
Extended Inquire.) 


contrl(3) — 
contrl(6) — 

Length of intin array = 0. 
Device handle. 


ptsin 

Array of coordinates of 

polyline in NDC/RC units. 


ptsin(O) 

ptsin(l) 

ptsin(2) 

ptsin(3) 

x-coordinate of first point in 
NDC/RC units. 

y-coordinate of first point in 
NDC/RC units. 

x-coordinate of second point 
in NDC/RC units. 

y-coordinate of second point 
in NDC/RC units. 


ptsin(2n-2) — 

ptsin(2n-l) — 

x-coordinate of last point in 
NDC/RC units. 

y-coordinate of last point in 
NDC/RC units. 


Output contrl(2) — Number of output vertices = 0. 

contr1(4) — Length of intout array = 0. 
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Polyline 


C BINDING 

Procedure Name v_pline( handle, count, pxyarray ) 


Data Types WORD v_pline ( ); 

WORD handle; 

WORD count; 

WORD pxyarray[2 * count]; 


Input Arguments handle = contrl[6] 

count = contr1[1] 
pxyarray[0] = ptsin[0] 
pxyarray[l] = ptsin[l] 


pxyarray[2n-2] = ptsin[2n-2] 
pxyarray[2n-l] = ptsin[2n-l] 
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Polymarker 


POLYMARKER This function draws markers at the points 

specified in the input array. GEM VDI dis¬ 
plays the markers using the current marker 
attributes: 


o color 
o scale 
o type 

o writing mode 


Input contrl(O) — 

contrl(l) -- 

contr1(3) — 
contrl(6) — 

ptsin 

ptsin(O) 

ptsin(l) 

ptsin(2) 

ptsin(3) 

ptsin(2n-2) - 
ptsin(2n-l) - 


Opcode = 7. 

Number of markers = n. 

(Maximum number is returned in 
Extended Inquire.) 

Length of intin array = 0. 
Device handle. 

Array of coordinates in NDC/RC 
units. 

x-coordinate of first marker 
in NDC/RC units, 
y-coordinate of first marker 
in NDC/RC units, 
x-coordinate of second marker 
in NDC/RC units, 
y-coordinate of second marker 
in NDC/RC units. 


x-coordinate of last marker in 
NDC/RC units. 

y-coordinate of last marker in 
NDC/RC units. 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 
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Polymarker 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_pmarker( handle, count, pxyarray ) 


WORD v_pmarker ( ); 

WORD handle; 

WORD count; 

WORD pxyarray[2 * count]; 


handle = contrl[6] 
count = contr1[1] 
pxyarray[0] = ptsin[0] 
pxyarray[l] = ptsin[l] 


# 

pxyarray[2n-2] = ptsin[2n-2] 
pxyarray[2n-l] = ptsin[2n-l] 
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Text 


TEXT This function writes graphic text to the dis¬ 

play surface. The (x,y) position specified 
by the application program is the alignment 
point of the text string. The Set Graphic 
Text Alignment function establishes the 

relationship between the starting point of 
the string and the specified x,y position. 
The default alignment is the left baseline 
position of the text string. Refer to the 
Set Graphic Text Alignment function in Sec¬ 
tion 5 for an illustration of alignment 
points. 

Each word of the intin array contains one 
character in bits 0-7. Any unsupported 
character is mapped to a symbol for an un¬ 
defined character. 


Input contr1(0) 

contrl(1) 
contrl(3) 
contrl(6) 

intin 


ptsin(0) 


ptsin(1) 


Opcode = 8. 

Number of input vertices = 1. 
Length of intin array = n. 
Device handle. 

Character string as ASCII 
codes in 16-bit words. 

The maximum number of charac¬ 
ters equals the size of the 
intin array. See Extended 
Inquire. 

x-coordinate of alignment 
point of text in NDC/RC 
units. 

y-coordinate of alignment 
point of text in NDC/RC units. 


Output 


contrl ( 2 ) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


4-6 




GEM VDI Programmer's Guide 


Text 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_gtext( handle, x, y, string ) 


WORD v_gtext ( ); 

WORD handle; 

WORD x; 

WORD y; 

BYTE string[n]; 


handle = contrl[6] 
x = ptsin[0] 
y = ptsin[l] 
string = intin 

Note; Bytes for the string array are mapped 
into the eight least significant bits of in¬ 
tin. The string must be null-terminated. 
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Filled Area 


FILLED AREA This function fills a complex (for example, 

self-intersecting) polygon specified by the 
input array. The area is filled using the 
following current attributes: 


o fill area color 

o interior style (hollow, solid, pattern, 
hatch or user-defined) 

o writing mode 

o style index 


The area is outlined with a solid line of the 
current fill area color if the fill area 
perimeter visibility is on, which is the 
default at Open Workstation. See the Set 
Fill Perimeter Visibility function in Section 
5. 


If a device does not have area fill 
capability, GEM VDI outlines the polygon 
using the current fill area color. The 
device driver ensures that the fill area is 
closed by connecting the first point to the 
last point. 

GEM VDI displays a polygon with zero area as 
a dot. If outline isn't turned on, the 
degenerate case isn't displayed as a dot. 
GEM VDI does not display a polygon with only 
one endpoint. The maximum number of filled 
area vertices may be determined with the 
Extended Inquire function. 
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Filled Area 


Input contrl(0) — 

contrl(1) — 

contrl(3) — 
contrl(6) — 

ptsin 

ptsin(O) — 
ptsin(l) -- 
ptsin(2) — 
ptsin(3) -- 

ptsin(2n-2) - 
ptsin(2n-l) - 


Opcode = 9. 

Number of vertices in polygon 
= n. 

Maximum number returned in 
Extended Inquire. 

Length of intin array = 0. 
Device handle. 

Array of coordinates of 
polygon in NDC/RC units, 
x-coordinate of first point in 
NDC/RC units. 

y-coordinate of first point in 
NDC/RC units. 

x-coordinate of second point 
in NDC/RC units, 
y-coordinate of second point 
in NDC/RC units. 


x-coordinate of last point in 
NDC/RC units. 

y-coordinate of last point in 
NDC/RC units. 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 0. 
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Filled Area 


C BINDING 

Procedure Name v_fillarea( handle, count, pxyarray ) 


Data Types WORD v_fillarea ( ); 

WORD handle; 

WORD count; 

WORD pxyarray[2 * count]; 


Input Arguments handle = contrl[6] 

count = contrl[l] 
pxyarray[0] = ptsin[0] 
pxyarray[l] = ptsin[l] 


pxyarray[2n-2] = ptsin[2n-2] 
pxyarray[2n-l] = ptsin[2n-l] 
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Cell Array 


CELL ARRAY 


Input 


With the Cell Array function, the device 
draws a rectangular array defined by the in¬ 
put parameter (x,y) coordinates and the color 
index array. The lower left and upper right 
coordinates define the extent of the rec¬ 
tangle. GEM VDI divides the rectangle into 
cells based on the number of rows and columns 
specified as input parameters. The color in¬ 
dex array specifies the color for each cell. 

Each cell of the rectangle is mapped to 
pixels on the display surface. The pixel 
takes the color of the cell that covers its 
center. 

If the device does not support cell arrays, 
the device outlines the area with a solid 
line in the current line color and line 
width. 

Note: This function is not required and may 
not be available on all devices. 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 
contrl(7) 


contrl(8) 
contrl(9) 
contrl(10 


intin(0) 
ptsin(0) 
ptsin(1) 
ptsin(2) 
ptsin(3) 


— Opcode = 10. 

— Number of input vertices = 2. 

— Length of color index array. 

-- Device handle. 

-- Length of each row in color index 
array (size as declared in a 
high-level language). 

— Number of elements used in each 
row of color index array. 

-- Number of rows in color index ar¬ 
ray. 

)-- Pixel operation to be performed. 

(See Set Writing Mode function in 
Section 5 for the description of 
each mode.) 

-- Color index array, stored by row. 

— x-coordinate of lower left corner 

in NDC/RC units. 

— y-coordinate of lower left corner 

in NDC/RC units. 

— x-coordinate of upper right corner 

in NDC/RC units. 

-- y-coordinate of upper right corner 
in NDC/RC units. 
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Cell Array 


Output 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 


contrl(2) -- Number of output vertices = 0. 
contrl(4) — Length of intin array = 0. 


v_cellarray( handle, pxyarray, row_length, 
el_used, num_rows, wrt_mode, colarray ) 


WORD v_cellarray( ); 

WORD handle; 

WORD pxyarray[4]; 

WORD row_length; 

WORD el_used; 

WORD num_rows; 

WORD wrt_mode; 

WORD colarray[num_rows*el_used]; 


handle = contrl[6] 
pxyarray[0] = ptsine[0] 
pxyarray[l] = ptsin[l] 
pxyarray[2] = ptsin[2] 
pxyarray[3] = ptsin[3] 
row_length = contrl[7] 
el_used = contrl[8] 
num_rows = contrl[9] 
wrt_mode = contrl[10] 
colarray[0] = intin[0] 


colarray[n] = intin[n] 
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Contour Fill 


CONTOUR FILL This function fills an area until it finds 

either the edges of the display surface or 
the color index stated in intin(O). This 
function is sometimes called a seed fill or 
flood fill. If intin(O) is negative, the al¬ 
gorithm searches for any color other than the 
color of the seed point. GEM VDI fills the 
area using the current fill area attributes. 

Note: This function is not required and may 

not be available on all devices. 


Input contrl(O) — Opcode = 103. 

contrl(l) -- Number of input vertices = 1. 

contrl(3) -- Length of intin array = 1. 

contrl(6) — Device handle. 

intin(O) — Color index that defines the 

contour. 

ptsin(O) — x-coordinate of starting point 
in NDC/RC units. 

ptsin(1) — y-coordinate of starting point 

in NDC/RC units. 


Output contrl(2) -- Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 


C BINDING 

Procedure Name v_contourfill( handle, x, y, index ) 


Data Types WORD v_contourfill( ); 

WORD handle; 

WORD x; 

WORD y; 

WORD index; 


Input Arguments handle = contrl[6] 

x = ptsin[0] 
y = ptsin[l] 
index = intin[0] 
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Contour Fill 


FILL RECTANGLE This function fills a rectangular area with 

the pattern defined by the current fill area 
attributes. The rectangle is filled using 
all fill area attributes except outline. 


Input contrl(0) — 

contrl(l) -- 
contrl(3) — 
contrl(6) — 

ptsin(O) 

ptsin(l) 

ptsin(2) 


ptsin(3) 


Opcode = 114. 

Number of input vertices = 2. 
Length of intin array = 0. 
Device handle. 

x-coordinate of corner of des¬ 
tination rectangle in RC/NDC. 
y-coordinate of corner of des¬ 
tination rectangle in RC/NDC. 
x-coordinate of corner of des¬ 
tination rectangle in RC/NDC 
diagonally opposite corner 
specified in ptsin(O). 
y-coordinate of corner of des¬ 
tination rectangle in RC/NDC 
diagonally opposite corner 
specified in ptsin(1). 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 

Procedure Name vr_recfl( handle, pxyarray ) 


Data Types WORD vr_recf1 ( ); 

WORD handle; 

WORD pxyarray[4]; 


Input Arguments 


handle = contrl[6] 
pxyarray[0] = ptsin[0] 


pxyarray[3] = ptsin[3] 
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GDP 


GENERALIZED 
DRAWING PRIMITIVE 
(GDP) 


Input 


The Generalized Drawing Primitive (GDP) 
function allows you to use the predefined 
primitives. The application can draw special 
elements, such as arcs, circles, and ellipses 
using this function. 

The contents of the control and data arrays 
are different for each GDP. 

For the arc, pie, elliptical arc, and ellip¬ 
tical pie, the information in the radius, 
start, and end angle variables defines the 
GDP. 

All angle specifications are in tenths of de¬ 
grees and assume that 0 degrees is 90 de¬ 
grees to the right of vertical, with values 
increasing in the counterclockwise direc¬ 
tion. Arcs are drawn counterclockwise. All 
radius specifications except for ellipse and 
elliptical arc, assume an extent (distance) 
in the x-axis. Ellipse and elliptical arc 
use both x and y radius values. Refer to 
Figure 4-2. 

900 


1800 


0 


2700 

Figure 4-2. Angle Specification 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 


Opcode = 11. 

Number of vertices in ptsin. 
Length of input array intin. 
Primitive id. 


1 — BAR: Uses fill area attributes 

(fill interior style, style 

index, writing mode, color and 

perimeter style). 

4 -- CIRCLE: Uses fill area attributes 

(fill interior style, style 

index, writing mode, fill 
color and perimeter style). 
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GDP 


2 — 

3 — 

5 — 

6 — 

7 — 

8 — 

9 — 

10 - 


ARC: Uses line attributes (color, 

linetype, writing mode, 

width, and end styles). 

PIE: Uses fill area attributes (in¬ 

terior style, writing mode, 
fill style, fill color, and 
perimeter style). 

ELLIPSE: Uses fill area attributes 

(fill interior style, writing 
mode, style index, color, and 
perimeter style). 

ELLIPTICAL 

ARC: Uses line attributes (color, 

linetype, writing mode, 

width, and end styles). 

ELLIPTICAL 

PIE: Uses fill area attributes 

(fill interior style, writing 
mode, style index, color and 
perimeter style). 

ROUNDED 

RECTANGLE: 

Uses line attributes (color, 
linetype, writing mode, and 
width). 

FILLED 

ROUNDED 

RECTANGLE: 

Uses fill area attributes 
(fill interior style, writing 
mode, style index color, and 
perimeter style, color, and 
width). 

JUSTIFIED 

GRAPHICS 

TEXT: Uses text attributes (face, 

character height, character 
baseline vector, color index, 
special effects, and align¬ 
ment ). 


contrl(6) -- Device handle. 


ptsin — Array of coordinates for GDPs 

in NDC/RC units. 


ptsin(O) — x-coordinate of first point in 
NDC/RC units. 

ptsin(l) -- y-coordinate of first point in 
NDC/RC units. 
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GDP 


ptsin(2) 

ptsin(3) 

ptsin(2n-2) 
ptsin(2n-l) 

intin 


x-coordinate of second point 
in NDC/RC units, 
y-coordinate of second point 
in NDC/RC units. 


-- x-coordinate of last point in 
NDC/RC units. 

— y-coordinate of last point in 
NDC/RC units. 

— Angle for arcs and pies or 
characters for justified 
graphics text. 


4-17 



GEM VDI Programmer's Guide 


BAR 


BAR 

Input contrl(O) -- Opcode = 11. 

contrl(l) -- Number of input vertices = 2. 
contrl(3) -- Length of intin array = 0. 

contrl(5) — Primitive id = 1. 

contrl(6) -- Device handle. 

ptsin(O) -- x-coordinate of corner of bar 

in NDC/RC units. 

ptsin(l) -- y-coordinate of corner of bar 
in NDC/RC units. 

ptsin(2) — x-coordinate of corner diagon¬ 
ally opposite the corner 

selected in ptsin(O) of bar 

in NDC/RC units. 

ptsin(3) -- y-coordinate of corner diagon¬ 
ally opposite the corner 

selected in ptsin(l) of bar 

in NDC/RC units. 


Output contrl(2) — Number of output vertices - 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 

Procedure Name v_bar( handle, pxyarray ) 


Data Types WORD v_bar ( ); 

WORD handle; 

WORD pxyarray[4]; 


Input Arguments handle = contrl[6] 

pxyarray[0] = ptsin[0] 
pxyarray[l] = ptsin[l] 
pxyarray[2] = ptsin[2] 
pxyarray[3] = ptsin[3] 
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ARC & PIE 


ARC & PIE 

These functions are not required and may not 
be available on all devices. GEM VDI re¬ 
quires the specification of the arc by the 
angle (intin(0),intin(1)). 

Input 

contrl(0) 

_ 

Opcode = 11. 


contrl(1) 

— 

Number of input vertices = 4. 


contrl(3) 

— 

Length of intin array = 2. 


contrl(5) 


Primitive id. 

2 = ARC 

3 = PIE 


contrl(6) 


Device handle. 


intin(0) 

— 

Start angle (in tenths of de¬ 
grees 0-3600), counterclock¬ 
wise. 


intin(1) 


End angle (in tenths of de¬ 
grees 0-3600). 


ptsin(0) 

— 

x-coordinate of center point 
of arc in NDC/RC units. 


ptsin(1) 

— — 

y-coordinate of center point 
of arc in NDC/RC units. 


ptsin(2) 


0. 


ptsin(3) 

-- 

0. 


ptsin(4) 

-- 

0. 


ptsin(5) 

— 

0. 


ptsin(6) 

"" 

Radius in x-coordinate NDC/RC 
units. 


ptsin(7) 

-- 

0. 


Output 

contrl(2) — 

Number 

of 

output 

vertices = 0. 


contrl(4) — 

Length 

of 

intout 

array = 0. 
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ARC & PIE 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_arc( handle, x, y, radius, begang, endang ) 
v_pieslice( handle, x, y, radius, begang, 
endang ) 


WORD v_arc ( ); 

WORD handle; 
WORD x, y; 

WORD radius; 


handle = contrl[6] 
x = ptsin[0] 
y = ptsin[l] 
radius = ptsin[6] 
begang = intin[0] 
endang = intin[l] 
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CIRCLE 

CIRCLE 

This function is not required 
supported on all devices. 

and may not be 


Input 

contrl(0) 

-- 

Opcode = 11. 


contrl(1) 

-- 

Number of input vertices = 3. 


contrl(3) 

-- 

Length of intin array = 0. 


contrl(5) 

— 

Primitive id = 4. 


contrl(6) 

— 

Device handle. 


ptsin(O) 

— 

x-coordinate of center point 
of circle in NDC/RC units. 


ptsin(1) 

— — 

y-coordinate of center point 
of circle in NDC/RC units. 


ptsin(2) 

— 

0. 


ptsin(3) 

— 

0. 


ptsin(4) 


Radius in x-coordinate NDC/RC 
units. 


ptsin(5) 


0. 

Output 

contrl(2) 

_ _ 

Number of output vertices = 0. 


contrl(4) 


Length of intout array = 0. 


C BINDING 

Procedure Name v_circle( handle, x, y, radius ) 


Data Types WORD v_circle ( ); 

WORD handle; 

WORD x, y; 

WORD radius; 


Input Arguments handle = contrl[6] 

x = ptsin[0] 
y = ptsin[l] 
radius = ptsin[4] 
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ELLIPTICAL ARC and PIE 


ELLIPTICAL ARC 
AND PIE 

Input contr1(0) — 

contr1(1) — 
contrl(3) — 
contr1(5) — 

contrl(6) -- 
intin(O) 

intin(l) 

ptsin(O) 

ptsin(l) 

ptsin(2) 

ptsin(3) 


Opcode = 11. 

Number of input vertices = 2. 
Length of intin array = 2. 
Primitive id. 

6 = ELLIPTICAL ARC 

7 = ELLIPTICAL PIE SLICE 

Device handle. 

Start angle (in tenths of de¬ 
grees 0-3600), counterclock¬ 
wise. 

End angle (in tenths of de¬ 
grees 0-3600). 

x-coordinate of center point 
of arc in NDC/RC units. 


y-coordinate of center point 
of arc in NDC/RC units. 


Radius 

units. 

of 

X-axis 

in 

NDC/RC 

Radius 
units. 

of 

Y-axis 

in 

NDC/RC 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0 
Length of intout array = 0. 
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ELLIPTICAL ARC and PIE 


C BINDING 
Procedure Name 


Data Types 


Input Arguments 


v_ellarc( handle, x, y, xradius, 
begang, endang ) 

v_ellpie( handle, x, y, xradius, 
begang, endang ) 


WORD v_ellarc ( ); 

WORD v_ellpie ( ); 

WORD handle; 

WORD x, y; 

WORD xradius; 

WORD yradius; 

WORD begang; 

WORD endang; 


handle = contrl[6] 
x = ptsin[0] 
y = ptsin[l] 
xradius = ptsin[2] 
yradius = ptsin[3] 
begang = intin[0] 
endang = intin[l] 


yradius, 
yradius. 
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ELLIPSE 


ELLIPSE 

Input contrl(O) — Opcode = 11. 

contrl(l) — Number of input vertices = 2. 

contrl(3) — Length of intin array = 0. 

contrl(5) — Primitive id = 5. 

contrl(6) — Device handle. 

ptsin(O) — x-coordinate of center point 

of ellipse in NDC/RC units. 
ptsin(1) — y-coordinate of center point 

of ellipse in NDC/RC units. 
ptsin(2) — Radius of X-axis in NDC/RC 

units. 

ptsin(3) — Radius of Y-axis in NDC/RC 

units. 


Output contr1(2) — Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 


C BINDING 

Procedure Name v_ellipse( handle, x, y, xradius, yradius ) 


Data Types WORD v_ellipse ( ); 

WORD handle; 

WORD x, y; 

WORD xradius; 

WORD yradius; 


Input Arguments handle = contrl[6] 

x = ptsin[0] 
y = ptsin[l] 
xradius = ptsin[2] 
yradius = ptsin[3] 
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ROUNDED AND FILLED A rectangle with rounded corners is output to 
ROUNDED RECTANGLE the workstation. The rectangle is defined by 

specifying its lower left and upper right 
corners. 

The Rounded Rectangle GDP assumes the at¬ 
tributes of a polyline primitive. The Filled 
Rounded Rectangle GDP assumes the attributes 
of a filled area primitive. 


Input contrl( 0 ) — 

contrl(l) -- 
contrl(3) — 
contrl(5) — 


contrl(6) — 
ptsin(O) 

ptsin(l) 

ptsin(2) 


ptsin(3) 


Opcode = 11. 

Number of input vertices = 2. 
Length of intin array = 0. 
Primitive id. 

8 = Rounded Rectangle 

9 = Filled Rounded Rectangle 

Device handle. 

x-coordinate of corner of rec¬ 
tangle in NDC/RC units, 
y-coordinate of corner of rec¬ 
tangle in NDC/RC units, 
x-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(O) of rectangle in 

NDC/RC units. 

y-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(1) of rectangle in 
NDC/RC units. 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 0. 
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C BINDING 
Procedure Name 

Data Types 


Input Arguments 


v_rbox( handle, xyarray ) 
v_rfbox( handle, xyarray) 


WORD ( v_rbox ); 
WORD ( vrfbox ); 
WORD handle; 

WORD xyarray[4]; 


handle = contrl[6]; 
attributes = intin[0] 
xyarray[0] = ptsin[0] 
xyarray[l] = ptsin[l] 
xyarray[2] = ptsin[2] 
xyarray[3] = ptsin[3] 
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Justified Graphics Text 


JUSTIFIED GRAPHICS This function outputs graphics text to the 
TEXT workstation display surface and attempts to 

perform both left and right justification. 
The text string is aligned at the requested 
string alignment points passed in, using the 
current text alignment attributes. 

Extra spacing may be inserted or deleted by 
the driver between words or characters (or 
both) so that the string will have the re¬ 
quested length. Either form of spacing 
modification (inter-character or inter-word) 
can be suppressed by so specifying in the 
provided parameter. 


Input contrl(O) — Opcode = 11. 

contrl(l) -- Number of input vertices = 2. 

contrl(3) -- Length of intin array = 2 + n 

(characters in string). 
contrl(5) -- Primitive id = 10. 

contrl(6) -- Device handle. 

intin(O) — Inter-word spacing flag. 

0 = Doesn’t allow GEM VDI to 
modify inter-word spacing. 

nonzero = Allows GEM VDI to 
modify inter-word spacing. 

intin(l) -- Inter-character spacing flag. 

0 = Doesn't allow GEM VDI to 
modify inter-character 

spacing. 

nonzero = Allows GEM VDI to 
modify inter-character 

spacing. 

intin(2) — First character of text 
string. 


intin(n+l) — Last character of text string. 
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Justified Graphics Text 


ptsin(O) 

x-coordinate of 

the 

text 


alignment 
units. 

point. 

in 

NDC/RC 

ptsin(l) 

y-coordinate of 

the 

text 


alignment 

units. 

point. 

in 

NDC/RC 

ptsin(2) 

Requested 

length 

of the 


string. 

in x-axis 

NDC/RC 


units. 




ptsin(3) 

0 . 





Output contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 
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Justified Graphics Text 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 


v_justified(handle, x, y, string, length, 
word_space, char_space); 


WORD v_justified(); 
WORD handle; 

WORD x, y; 

WORD length; 

WORD word_space; 
WORD char_space; 
BYTE string[]; 


handle = contrl[6]; 
x = ptsin[0]; 
y = ptsin[l]; 
length = ptsin[2]; 
word_space = intin[0]; 
char_space = intin[l]; 
stringfj] = intin[j+2]; 

Note: Bytes for the string array are mapped 

into the eight least significant bits of in¬ 
tin words. 

Note: The string array must be null-ter¬ 

minated. 


End of Section 4 
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Section 5 

ATTRIBUTE FUNCTIONS 


INTRODUCTION 


SET WRITING MODE 


Attribute functions determine qualities of 
all subsequent output primitives such as 
color, type, style, and height. 


This function selects the writing mode used 
for subsequent drawing operations. The 
writing mode specifies the operation per¬ 
formed between the color indices of the cur¬ 
rent pixel (source) and the existing pixel 
(destination), thus affecting the way new 
pixels from lines, markers, filled areas, and 
text are placed on the display. Four modes 
exist: replace, transparent, XOR, and 
reverse transparent. If the requested 
writing mode is out of range, GEM VDI 
selects replace mode, 1. 

Table 5-1 lists the writing modes and their 
numerical assignments. 


Table 5-1. Writing Modes 
Number Mode 


1 Replace 

2 Transparent 

3 XOR 

4 Reverse Transparent 
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Set Writing Mode 


For the Boolean expressions of the modes 
given below, the definitions in Table 5-2 ap¬ 
ply. 


Table 5-2. Terms 


Term 

Definition 


mask 

line style or fill pattern 


fore 

selected color after mapping 
GEM VDI 

from 

back 

color 0 after mapping from 
VDI (white is default) 

GEM 

old 

current color value 


new 

replacement color value 



Replace Replace mode is insensitive to the currently 

displayed image. Any information already 
displayed is replaced. The following is the 
Boolean expression for replace mode: 

new = (fore AND mask) OR (back AND NOT mask) 


Transparent Transparent mode only affects the pixels 

where the mask is 1. These are changed to 
the fore value. The following is the Boolean 
expression for transparent mode: 

new = (fore AND mask) OR (old AND NOT mask) 


XOR XOR mode reverses the bits representing the 

color. The following is the Boolean expres¬ 
sion for XOR mode: 

new = mask XOR old 
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Reverse 

Transparent 

Reverse transparent mode only affects the 
pixels where the mask is 0. These are 
changed to the fore value. The following is 
the Boolean expression for reverse 
transparent mode: 

new = (old AND mask) OR (fore AND NOT mask) 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 

intin(O) 

Opcode = 32. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 

Writing mode requested. 

Output 

contrl(2) -- 
contrl(4) — 

intout(O) -- 

Number of output vertices = 0. 
Length of intout array = 1. 

Writing mode selected. 


C BINDING 


Procedure Name 
Data Types 


Input Arguments 


Output Arguments 


set_mode = vswr_mode( handle, mode ) 


WORD setjmode; 

WORD vswr_mode ( ); 

WORD handle; 

WORD mode; 


handle = contrl[6] 
mode = intin[0] 


set mode = intout[0] 
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Set Color Representation 


SET COLOR 
REPRESENTATION 

This function associates a color index with 
the color specified in RGB (Red, Green, Blue) 
units. On a monochrome device, GEM VDI maps 
any percentage of color to white. GEM VDi 
maps any color intensity of a value less 
than 0 to 0 and greater than 1000 to 1000. 
If the application requests a color index 
that is out of range, GEM VDI performs no 
operation. GEM VDI references the background 
color as color index zero. 


Note: If no color lookup table exists, GEM 
VDI performs no operation with this func¬ 
tion. The Extended Inquire function returns 
the availability of the lookup table. 

Input 

contrl(0) — Opcode = 14. 

contrl(l) -- Number of input vertices = 0. 

contrl(3) — Length of intin array = 4. 

contrl(6) -- Device handle. 


intin(0) — Color index. 

intin(1) -- Red color intensity (in tenths 

of percent, 0-1000). 
intin(2) — Green color intensity. 

intin(3) -- Blue color intensity. 

Output 

contrl(2) -- Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 
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Set Color Representation 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


vs_color( handle, index, rgb_in ) 


WORD vs_color ( ); 

WORD handle; 

WORD index; 

WORD rgb in[3]; 


handle = contrl[6] 
index = intin[0] 
rgb_in[0] = intin[l] 
rgb_in[l] = intin[2] 
rgb_in[2] = intin[3] 
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Set Polyline Line Type 


SET POLYLINE 
LINE TYPE 


This function sets the line type for 
subsequent polyline operations. The total 
number of line styles available is device¬ 
dependent, but all devices support at least 
six. If the requested line style is out of 
range, GEM VDI selects solid (1) line style. 
The pixel value in the pattern word is 1 = 
pixel on (active); 0 = pixel off. 

16 Bits 

Style MSB LSB 


1 solid 

2 long dash 

3 dot 

4 dash,dot 

5 dash 

6 dash,dot,dot 

7 user-defined 
style 


8-n device¬ 
dependent 


1111111111111111 

1111111111110000 

1110000011100000 

1111111000111000 

1111111100000000 

1111000110011000 

16 bits (1 word) 

Most Significant 

Bit = first pixel 

displayed. 


Line style seven, user-defined style, uses 
the pattern the Set User-defined Line Style 
Pattern function defines. This pattern 
defaults to solid until the user defines it. 

Note; If a nondefault line width is used, 
the device may draw the thickened line using 
a solid line style and may change the writing 
mode. 
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Set Polyline Line Type 


Input contrl(O) — Opcode = 15. 

contrl(1) — Number of input vertices = 0. 

contrl(3) — Length of intin array = 1. 

contrl(6) — Device handle. 

intin(O) — Requested line style. 


Output contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 1. 

intout(O) — Line style selected. 


C BINDING 

Procedure Name set_type = vsl_type( handle, style ) 


Data Types WORD set_type ; 

WORD vsl_type ( ); 

WORD handle; 

WORD style; 


Input Arguments handle = contrl[6] 

style = intin[0] 


Output Arguments set_type = intout[0] 
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SET USER-DEFINED This function sets the current user-defined 
LINE STYLE PATTERN line style pattern word in the device driver 

to the value in the specified 16-bit pattern 
word. 

The Most Significant Bit (MSB) of the pattern 
word is the first pixel in the line. This 
line style is used for subsequent polyline 
operations when the application selects 
user-defined line style, index 7. 


Input contrl(O) — Opcode = 113. 

contr1(1) — Number of input vertices = 0. 

contrl(3) — Length of intin array = 1. 

contrl(6) -- Device handle. 

intin(O) — Line style pattern word, 16 

bits. 


Output contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 

Procedure Name vsl_udsty( handle, pattern ) 


Data Types WORD vsl_udsty ( ); 

WORD handle; 

WORD pattern; 


Input Arguments handle = contrl[6] 

pattern = intin[0] 
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Set Polyline Line Width 


SET POLYLINE LINE This function sets the width of lines for 

WIDTH subsequent polyline operations. The avail¬ 

able line width closest to but not greater 
than the requested line width is used. Line 
widths are odd numbers that begin at three. 
If you select two in Raster Coordinates, GEM 
VDI returns one, which is a line one pixel 
wide. 

Note: This function is not required and may 

not be available on all devices. Thickened 
lines may be rendered on the device using 
solid line type, rather than a requested line 
type. 


Input contr1(0) 

contr1(1) 
contr1(3) 
contr1(6) 

ptsin(O) 

ptsin(1) 


Opcode = 16. 

Number of input vertices = 1. 
Length of intin array = 0. 
Device handle. 

Requested line width in x-axis 
in NDC/RC units. 

0 . 


Output 


contrl(2) — Number of output vertices = 1. 

contrl(4) — Length of intout array = 0. 


ptsout(0) 
ptsout(1) 


Selected line width in x-axis 
of the NDC/RC units. 

0 . 
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Set Polyline Line Width 


C BINDING 

Procedure Name set_width = vsl_width( handle, width ) 


Data Types WORD set_width; 

WORD vsl_width; 
WORD handle; 
WORD width; 


Input Arguments handle = contrl[6] 

width = ptsin[0] 


Output Arguments set_width = ptsout[0] 
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Set Polyline Color Index 

SET POLYLINE 

This function 

sets the color index for 

COLOR INDEX 

subsequent polyline operations. The Set 
Color Representation function determines the 
color the index represents. At least two 
color indices, 0 and 1, are supported 
(monochrome). Color indices range from 0 to 
a device-dependent maximum. If the applica¬ 
tion requests an index that is out of range, 
GEM VDI selects color index 1. 

Input 

contrl(O) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 

intin(O). — 

Opcode = 17. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 

Requested color index. 

Output 

contrl(2) -- 
contrl(4) — 

intout(0) — 

Number of output vertices = 0. 
Length of intout array = 1. 

Color index selected. 


C BINDING 

Procedure Name set_color = vsl_color( handle, color_index ) 


Data Types WORD set_color; 

WORD vsl_color ( ); 

WORD handle; 

WORD color index; 


Input Arguments 


handle = contrl[6] 
color index = intin[0] 


Output Arguments set_color = intout[0] 
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Set Polyline End Styles 


SET POLYLINE END 
STYLES 

This function 
a polyline, 
following: 

sets the style for the ends of 
The style may be any of the 


0 - squared 

1 - arrow 

2 - rounded 

(default) 


The two ends of a polyline may have different 
styles. If an invalid style is requested, a 
squared end style (0) is used. 


Both the squared style and the arrow style 
end at the end of the polyline. The rounded 
style is drawn such that the center of the 
rounding is at the end of the polyline. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) -- 
contrl(6) — 

Opcode = 108. 

Number of input vertices = 0. 
Length of intin array = 2. 
Device handle. 


intin(O) 

End style for beginning point 
of polyline. 



0 - squared (default) 

1 - arrow 

2 - rounded 


intin(l) 

End style for ending point of 
polyline. 



0 - squared (default) 

1 - arrow 

2 - rounded 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 0. 
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Set Polyline End Styles 


C BINDING 

Procedure Name 
Data Types 

Input Arguments 


vsl_ends( handle, beg_style, end_style ) 


WORD vsl_ends(); 
WORD handle; 

WORD beg_style; 
WORD end_style; 


handle = contrl[6]; 
beg_style = intin[0]; 
end_style = intin[l]; 
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Set Polymarker Type 


SET POLYMARKER This function sets the marker type for 
TYPE subsequent polymarker functions. The total 

number of markers available is device-depen¬ 
dent, but GEM VDI always defines at least six 
marker types: 


1 

2 

3 

4 

5 

6 
7 



Dot 

Plus 

Asterisk 

Square 

Diagonal Cross 
Diamond 

Device-dependent 


If the requested marker type is out of range, 
GEM VDI uses an asterisk, type 3. Marker 1 
is the smallest dot GEM VDI displays on the 
device; it cannot be scaled. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 18. 

Numbers of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(0) 


Requested polymarker type. 


Output 

contrl( 2 ) — 
contrl( 4 ) — 

Number of output vertices = 
Length of intout array = 1. 


intout( 0 ) — 

Polymarker type selected. 
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Set Polymarker Type 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


set_type = vsm_type( handle, symbol ) 


WORD set_type; 

WORD vsm_type ( ); 

WORD handle; 

WORD symbol; 


handle = contrl[6] 
symbol = intin[0] 


set_type = intout[0] 
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Set Polymarker Height 


SET POLYMARKER 
HEIGHT 

This function sets a polymarker height for 
subsequent polymarker functions. If the 
selected height does not exist, GEM VDI 
selects the next smaller height. The driver 
returns the actual height selected in the 
ptsout array. 

Input 

contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 

Opcode = 19. 

Number of input vertices = 1. 
Length of intin array = 0. 
Device handle. 


ptsin(0) 
ptsin(1) 

0. 

Requested polymarker height in 
y-axis in NDC/RC units. 

Output 

contrl(2) 
contrl(4) 

— Number of output vertices = 1. 

Length of intout array = 0. 


ptsout(0) 

ptsout(1) 

Polymarker width selected in 
x-axis in NDC/RC units. 
Polymarker height selected in 
y-axis in NDC/RC units. 


C BINDING 

Procedure Name set_height = vsm_height( handle, height ) 


Data Types WORD set_height; 

WORD vsm_height ( ); 

WORD handle; 

WORD height; 


Input Arguments handle = contrl[6] 

height = ptsin[l] 

Output Arguments set__height = ptsout[l] 
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Set Polymarker Color Index 


This function sets the color index for 
subsequent polymarker functions. The Set 
Color Representation function specifies the 
value of the index. At least two color in¬ 
dices are always supported (monochrome). If 
the index is out of range, GEM VDI selects 
color index 1. 


Input 

contrl(0) — 
contrl(1) — 
contrl(3) -- 
contrl(6) — 

Opcode = 20. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(O) 

Requested polymarker color in¬ 
dex. 

Output 

contrl(2) — 
contrl(4) — 

number of output vertices = 0. 
length of intout array = 1. 


intout(O) — 

Polymarker color index 

selected. 


C BINDING 


Procedure Name set_color = vsm_color( handle, color_index ) 


Data Types WORD set_color; 

WORD vsm_color ( ); 

WORD handle; 

WORD color index; 


Input Arguments handle = contrl[6] 

color index = intin[0] 


Output Arguments set_color = intout[0] 


SET POLYMARKER 
COLOR INDEX 
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Set Character Height, Absolute Mode 


SET CHARACTER This function sets the current graphic text 
HEIGHT, character height in NDC/RC units. The 
ABSOLUTE MODE specified height is the distance from the 

character baseline to the top of the charac¬ 
ter cell, rather than the character cell 
height. 

GEM VDI returns the selected height and width 
information to the application. GEM VDI 
returns both the distance from the baseline 
to top line selected and the size of a 
character cell. (See Figure 5-1 under "Set 
Character Height, Points Mode.") For fixed 
(monospaced) faces GEM VDI returns the width 
of a character and the width of a character 
cell. For proportional faces, GEM VDI 
returns the width of the widest character and 
the width of the widest character cell in the 
face. 

If the desired character height does not map 
exactly to a device size, GEM VDI selects the 
closest character size that does not exceed 
the requested size. 

The following numbers select Atari ST inter¬ 
nal system fonts: 

4 6x6 

6 8x8 

13 8 x 16 


Input contrl(O) — Opcode = 12. 

contrl(l) -- Number of input vertices = 1. 

contrl(3) — Length of intin array = 0. 

contrl(6) -- Device handle. 

ptsin(O) -- 0. 

ptsin(l) -- Requested character height in 

NDC/RC units. 


Output contrl(2) -- Number of output vertices = 2. 

contrl(4) -- Length of intout array = 0. 
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Set Character Height, Absolute Mode 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


ptsout(0) 
ptsout(1) 
ptsout(2) 
ptsout(3) 


Character width selected in 
NDC/RC units. 

Character height selected in 
NDC/RC units. 

Character cell width in NDC/RC 
units. 

Character cell height in 
NDC/RC units. 


vst_height( handle, height, &char_width, 

&char_height, &cell_width, &cell_height ) 


WORD vst_height ( ); 

WORD handle; 

WORD height; 

WORD char_width; 
WORD char_height; 
WORD cell_width; 
WORD cell height; 


handle = contrl[6] 
height = ptsin[l] 


char_width = ptsout[0] 
char_height = ptsout[l] 
cell_width = ptsout[2] 
cell_height = ptsout[3] 
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Set Character Height, Absolute Mode 


SET CHARACTER CELL 
HEIGHT, POINTS 
MODE 


Input 


This function sets the current graphic text 
character height in printer points. A point 
is 1/72 of an inch. The specified height is 
the distance between the baseline of one 
line of text and the baseline of the next 
line of text, which is the character cell 
height. 

The driver returns the selected point size of 
the character. Height and width information 
is returned in NDC/RC units. GEM VDI returns 
the character height, character width, cell 
height, and the cell width, as shown in 
Figure 5-1. For proportional faces, GEM VDI 
returns the width of the widest character and 
the widest character cell in the face. 

If the desired character height does not map 
exactly to a device size, GEM VDI selects the 
closest character size not exceeding the re¬ 
quested size. 

Left Character Right Character 

Alignment Alignment 

Delta Delta 



Character 
Height I 

I Cell Height 


Character 


Width 


Cell Width 


Figure 5-1. Character Cell Definition 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 107. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(0) 


Cell height in points. 
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Set Character Height, Points Mode 


Output 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


contrl(2) — 
contrl(4) — 

Number of output vertices = 
Length of intout array = 1. 

2. 

intout(0) — 

Selected cell height 

points. 

in 

ptsout(0) — 

Character width selected 
NDC/RC units. 

in 

ptsout(l) — 

Character height selected 
NDC/RC units. 

in 

ptsout(2) — 

Character cell width in NDC/RC 
units. 

ptsout(3) — 

Character cell height 

NDC/RC units. 

in 


set_point = vst_point( handle, point, 

&char_width, &char_height, &cell_width, 
&cell_height ) 


WORD set_point; 
WORD vst_point( ); 
WORD handle; 

WORD point; 

WORD char_width; 
WORD char_height; 
WORD cellwidth; 
WORD cell_height; 


handle = contrl[6] 
point = intin[0] 


set_point( ) = intout[0] 
char_width = ptsout[0] 
char_height = ptsout[l] 
cell_width = ptsout[2] 
cell_height = ptsout[3] 
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Set Character Height, Points Mode 


SET CHARACTER This function requests an angle of rotation 

BASELINE VECTOR specified in tenths of degrees for the 

character baseline vector, which specifies 
the baseline for subsequent graphic text. 
The driver returns the selected baseline 
vector to the application. The selected 
baseline vector is a best-fit match to the 
requested value. 

See Figure 5-2 for a depiction of how angles 
are specified to GEM VDI. 

900 


1800 


0 


2700 

Figure 5-2. Angle Specification 


Note: This function is not required and may 
not be supported on all devices. The 
Extended Inquire function returns the 
availability of this function. 


Input 

contrl(0) -- 

Opcode = 13. 


contrl(l) -- 

Number of input vertices = 0. 


contrl(3) — 

Length of intin array = 1. 


contrl(6) — 

Device handle. 


intin(0) 

Requested angle of rotation of 
character baseline (in tenths 
of degrees, 0 - 3600). 


Output 


contrl(2) 
contrl(4) 

intout(0) 


Number of output vertices = 0. 
Length of intout array = 1. 
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Angle of rotation of character 
baseline selected (in tenths 
of degrees 0-3600). 
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Set Character Baseline Vector 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


set_baseline = vst_rotation( handle, angle ) 


WORD set_baseline; 

WORD vst_rotation ( ); 

WORD handle; 

WORD angle; 


handle = contrl[6] 
angle = intin[0] 


set_baseline = intout[0] 
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Set Text Face 


SET TEXT FACE This function selects a graphic character 

face for subsequent graphic text operations. 
Face 1 is a built-in face. The other faces 
are external and may be loaded with the Load 
Face function. Some faces may not be sup¬ 
ported on all devices. Face names and in¬ 
dices may be determined by using Inquire 
Face Name. 


Input contrl(O) -- 

contrl(l) — 
contrl(3) -- 
contrl(6) -- 
intin(O) 


1 - System face 

2 - Swiss 721 

3 - Swiss 721 Thin 

4 - Swiss 721 Thin Italic 

5 - Swiss 721 Light 

6 - Swiss 721 Light Italic 

7 - Swiss 721 Italic 

8 - Swiss 721 Bold 

9 - Swiss 721 Bold Italic 

10 - Swiss 721 Heavy 

11 - Swiss 721 Heavy Italic 

12 - Swiss 721 Black 

13 - Swiss 721 Black Italic 

14 - Dutch 801 Roman 

15 - Dutch 801 Italic 

16 - Dutch 801 Bold 

17 - Dutch 801 Bold Italic 


Opcode = 21. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 

Requested software text face 
number«. 


Output contrl(2) -- Number of output vertices = 0. 

contrl(4) — Length of intout array = 1. 

intout(0) -- Text face selected. 
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Set Text Face 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


set_font = vst_font( handle. 


WORD set_font; 

WORD vst_font ( ); 

WORD handle; 

WORD font; 


handle = contrl[6] 
font = intinfO] 


set font = intout[0] 


font ) 
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Set Graphic Text Color Index 


SET GRAPHIC TEXT This function sets the color index for 
COLOR INDEX subsequent graphic text operations. The Set 

Color Representation function determines the 
color represented by the color index. All 
devices support at least two color indices, 
0 and 1 (monochrome). Color indices range 
from 0 to a device-dependent maximum. If the 
requested index is out of range, GEM VDI 
selects color index 1. 


Input contrl(0) — Opcode = 22. 

contrl(l) -- Number of input vertices = 0. 

contrl(3) -- Length of intin array = 1. 

contrl(6) — Device handle. 

intin(O) -- Requested text color index. 


Output 

contrl(2) — 

Number of output 

vertices = 0. 


contrl(4) — 

Length of intout 

array = 1. 


intout(O) -- 

Text color index 

selected. 


C BINDING 


Procedure Name set_color = vst_color( handle, color_index ) 


Data Types WORD set_color; 

WORD vstcolor ( ); 

WORD handle; 

WORD color index; 


Input Arguments handle = contrl[6] 

color index = intin[0] 


Output Arguments set_color = intout[0] 
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Set Graphic Text Special Effects 


SET GRAPHIC TEXT 
SPECIAL EFFECTS 


This function sets text special effects for 
subsequently displayed graphic text. The 
following effects are available: 


o thickened 
o light intensity 
o skewed 
o underlined 
o outlined 
o shadowed 

o any combination of the above 


GEM VDI treats the integer in intin(O) as a 
bit pattern. The attributes set correspond 
to the setting in the six least significant 
bits. 


Table 5-3, 
Bit Value 


0 

1 


4 


0 

1 


0 

1 


0 

1 


0 

1 


0 

1 


Attribute Bit Mapping 

Description 

Thickened 

thickened not selected 
set style to thickened 

Intensity 

normal intensity 
light intensity 

Skewed 

skewed not selected 
set style to skewed 

Underlined 

do not underline 
text is underlined 

Outline 

no outline 
outline 

Shadow 

no shadow 
shadow 
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Set Graphic Text Special Effects 


For example, if intin(O) = 9 (1001 binary), 
the text style is set to thickened and un¬ 
derlined. 

For effects not supported on a device, GEM 
VDI returns those bits set to 0. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 106. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(0) 


Special effect word. 


Output contrl( 2 ) 

contrl(4) 

intout(0) 


Number of output vertices = 0. 
Length of intout array = 1. 

Styles actually selected 
(style word with the ap¬ 
propriate bits set). 


Normal ABCDE 
Thickened ABCDE 

Light Intensity 

$ & 

Skewed ABCDE 
Underlined ABCDE 

Outli 


LJ W' L/ 


ned /^, |i! C |i I 


Figure 5-3. Graphic Text Special Effects 
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Set Graphic Text Special Effects 


C BINDING 

Procedure Name set_effect = vst_effects( handle, effect ) 


Data Types WORD set_effect; 

WORD vst_effects( ); 
WORD handle; 

WORD effect; 


Input Arguments handle = contrl[6] 

effect = intin[0] 


Output Arguments set_effect = intout[0] 
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Set Graphic Text Alignment 


SET GRAPHIC TEXT 
ALIGNMENT 


This function sets horizontal and vertical 
alignment for graphic text. Horizontal means 
in the direction of the baseline; vertical is 
perpendicular to the baseline. This function 
controls the positioning of the text string 
in relation to the graphic text position. 
The default alignment places the left 
baseline corner of the string at the graphic 
text position. 


If the application requests an invalid 
horizontal alignment, GEM VDI selects the 
default, left. If the application requests 
an invalid vertical alignment, GEM VDI 
selects the default, baseline. 



Top Line 
Ascent Line 

Half Line 

Base Line 

Descent Line 

Bottom Line 
Ascent Line 

Half Line 

Base Line 

Descent Line 


Top Line 
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Set Graphic Text Alignment 

Input 

contrl(O) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 

Opcode = 39. 

Number of input vertices = 0. 
Length of intin array = 2. 
Device handle. 


intin(O) 

Horizontal alignment requested 



0 = left justified (default) 

1 = center justified 

2 = right justified 


intin(l) 

Vertical alignment requested 



0 = baseline (default) 

1 = half line 

2 = ascent line 

3 = bottom 

4 = descent 

5 = top 

Output 

contrl(2) -- 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 2. 


intout(0) — 
intout(l) -- 

Horizontal alignment selected. 
Vertical alignment selected. 


C BINDING 


Procedure Name vst_alignment( handle, hor_in, vert_in, 

&hor_out, &vert out ) 


Data Types WORD vst_alignment( ); 

WORD handle; 

WORD hor_in; 

WORD vert_in; 

WORD hor_out; 

WORD vert out; 


Input Arguments handle = contrl[6] 

hor_in = intin[0] 
vert in = intin[l] 


Output Arguments hor_out = intout[0] 

vert_out = intout[1] 
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Set Fill Interior Style 


This function sets the fill interior style 
used in subsequent polygon fill operations. 
If the application requests an unavailable 
style, the area is hollow filled. GEM VDI 
returns the selected style to the applica¬ 
tion. Hollow style fills the interior with 
the current background color(index 0). Solid 
style fills the area with the currently 
selected fill color. 


Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 

Opcode = 23. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(O) 

Requested fill interior style. 



0 - hollow 

1 - solid 

2 - pattern 

3 - hatch 

4 - user-defined style 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 1. 


intout(0) — 

Fill interior style selected. 


C BINDING 


Procedure Name set_interior = vsf_interior( handle, style ) 


Data Types WORD set_interior; 

WORD vsf_interior ( ); 

WORD handle; 

WORD style; 


Input Arguments handle = contrl[6] 

style = intin[0] 


SET FILL INTERIOR 
STYLE 
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Set Fill Interior Style 
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Set Fill Style Index 


Note: l,n (i.e., Style 1, followed by any 
index) produces the same result as 2,8. 

For patterns, index 1 maps to the lowest in¬ 
tensity pattern on the device. The pattern 
is always monochrome and uses the current 
fill area color for foreground pixels. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 24. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(0) 


Requested fill style index for 
pattern or hatch fill. 


Output 

contrl(2) — 
contrl(4) — 

Number of output 
Length of intout 

vertices = 
array = 1 . 


intout(O) — 

Fill style index selected 
pattern or hatch fill. 


C BINDING 
Procedure Name 


setstyle = vsf style( handle, style_index ) 


Data Types 


WORD set_style; 

WORD vsf_style ( ); 

WORD handle; 

WORD style_index; 


Input Arguments 


handle = contrl[6] 
style_index = intin[0] 


Output Arguments set_style = intout[0] 
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Set Fill Color Index 


SET FILL COLOR This function sets the color index for 
INDEX subsequent polygon fill functions. The Set 

Color Representation function determines the 
color represented by the color index. All 
devices support at least two color indices, 
0 and 1 (monochrome). Color indices range 
from 0 to a device-dependent maximum. If the 
requested index is out of range, GEM VDI 
selects color index 1. 


Input contrl(O) — Opcode = 25. 

contr1(1) — Number of input vertices = 0. 

contrl(3) -- Length of intin array = 1. 

contrl(6) -- Device handle. 

intin(O) — Requested fill color index. 


Output contrl(2) -- Number of output vertices = 0. 

contrl(4) — Length of intout array = 1. 

intout(O) — Fill color index selected. 


C BINDING 

Procedure Name set_color = vsf_color( handle, color index ) 


Data Types WORD set_color; 

WORD vsf_color ( ); 
WORD handle; 

WORD color index; 


Input Arguments handle = contrl[6] 

color index = intin[0] 


Output Arguments set_color = intout[0] 
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Set Fill Color Index 


SET FILL PERIMETER 
VISIBILITY 

This function turns the outline of a fill 
area on or off. When visibility is on (the 
default at Open Workstation) the border of a 
fill area is drawn in the current fill area 
color with a solid line. When visibility is 
off, no outline is drawn. Any nonzero value 
of the visibility flag causes the perimeter 
to be visible. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(6 ) — 

Opcode = 104. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(O) 

Visibility flag. 



zero - invisible 

nonzero - visible 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 1. 


intout(0) — 

Visibility selected. 


C BINDING 

Procedure Name setperimeter = vsf perimeter( handle, pervis ) 


Data Types WORD set_perimeter; 

WORD vsf_perimeter ( ); 

WORD handle; 

WORD per_vis; 


Input Arguments handle = contrl[6] 

per_vis = intin[0] 


Output Arguments set_perimeter = intout[0] 
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Set User-defined Fill Pattern 


SET USER-DEFINED This function redefines the user-definable 
FILL PATTERN fill pattern. 

For the pattern data, bit 15 of word 1 is the 
upper left bit of the pattern. Bit 0 of 
word 16 is the lower right bit of the pat¬ 
tern. Bit zero is the Least Significant Bit 
of the word. Words are stored in the same 
format as 16-bit integers 

For a single plane pattern, a bit value of 1 
indicates foreground color. A bit value of 0 
indicates the background color. The color 
used for the foreground is determined by the 
current fill area color index. 

For a multiple plane pattern, the number of 
full 16-by-16 planes defined are used in the 
fill operation: planes = contrl(3) / 16. 
Any unspecified planes are zeroed. Note that 
the writing mode must be set to replace (mode 
1), when using a multiplane fill pattern, 
and the foreground must be set to 1. 

The defined pattern is referenced by the Set 
Fill Interior Style function as style 4 and 
by the Fill Rectangle function. 


Input contrl( 0 ) — 

contrl(1) — 
contrl(3) — 

contrl(6) — 

intin(O) to 
intin(15) — 
intin(16) to 
intin(29) — 


intin(n-15) to 
intin(n) 


Opcode = 112. 

Number of input vertices = 0. 
Length of intin array = 16 to 
n. 

Device handle. 


First plane of fill pattern. 
Second plane of fill pattern. 


Last plane of fill pattern. 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 0. 






GEM VDI Programmer's Guide 


Set User-defined Fill Pattern 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


vsf_udpat( handle, pfill_pat, planes ) -> 


WORD vsf_udpat; 

WORD handle; 

WORD pfill_pat[16 x n where n > 0] 
WORD planes; 


handle = contrl[6] 
pfill_ 


pfill_pat 

planes = contrl[3]/16 


End of Section 5 
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Section 6 
RASTER OPERATIONS 


INTRODUCTION 


MEMORY FORM 
DEFINITION BLOCK 


Raster operations perform logic operations 
on rectangular blocks of bits in memory and 
on rectangular blocks of pixels on physical 
devices. 


A raster area is defined by a Memory Form 
Definition Block (MFDB). An MFDB consists of 
the following components: 


o A 32-bit pointer to the memory address of 
the upper left corner of the first plane 
of the raster area. This pointer cor¬ 
responds to an offset-segment pointer for 
8086-based microcomputers. If all 32 bits 
of this pointer are 0, the MFDB is for a 
physical device, and the other parameters 
are ignored. 

o The height and width of the raster area in 
pixels. 

o The width of the raster area in words. 
This value is equal to the width of the 
raster area in pixels, divided by the word 
size. 

o The number of planes in the raster area. 

o A flag indicating whether the format of the 
raster area is standard or device-depen¬ 
dent. 

o Some locations reserved for future use. 


A raster area must start on a word boundary 
and have a width that is an integral multiple 
of the word size. 


6-1 




GEM VDI Programmer's Guide 


Memory Form Definition Block 


Word 1 
Word 2 
Word 3 
Word 4 
Word 5 
Word 6 
Word 7 
Word 8 
Word 9 
Word 10 

Figure 6-1. Memory Form Definition Block 


Memory pointer word 1 


Memory pointer word 2 


Form Width in Pixels 


Form Height in Pixels 


Form Width in Words 


Form format flag 


Number of memory planes 


RESERVED 


RESERVED 


RESERVED 


RASTER AREA Two memory formats are associated with raster 

FORMATS areas: 

o device-specific format 
o well-defined standard format 

GEM VDI provides a function to transform a 
raster area from one format to another. You 
must transform a form before using Copy 
Raster. 

The form format flag can have two values: 

0 - The form is in device-specific format. 

1 - The form is in standard format. 

The layout of a standard form format is as 
follows (see also Figure 6-2): 
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Raster Area Formats 


o Plane based - The planes are contiguous 
blocks of memory, each having the same x,y 
resolution. A monochrome implementation 
has a single plane. A color index is 
mapped to a pixel value with each plane 
representing one bit in the value. Tables 
6-1 and 6-2 define the pixel-value-to- 
color-index mapping for eight-color and 
sixteen-color screens, respectively. 

o Most Significant Bit in a word (16-bit in¬ 
teger) is the leftmost bit in the image. 
Note that the data is stored in the same 
format as 16-bit integers. 

o Words are arranged sequentially along a row 
with the first word being on the left edge 
of the row. 


Table 6-1. Pixel Value to Color Index 
Mapping for 8-color Screens 


Pixel Value Color Index 


Color 


000 

001 

010 

Oil 

100 

101 

110 

111 


0 

2 

3 
6 

4 
7 

5 
1 


white 

red 

green 

yellow 

blue 

magenta 

cyan 

black 
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Raster Area Formats 


Table 6-2. Pixel Value to Color Index 
Mapping for 16-color Screens 


Pixel Value 

Color Index 

Color 

0000 

0 

white 

0001 

2 

red 

0010 

3 

green 

0011 

6 

yellow 

0100 

4 

blue 

0101 

7 

magenta 

0110 

5 

cyan 

0111 

8 

low white 

1000 

9 

grey 

1001 

10 

light red 

1010 

11 

light green 

1011 

14 

light yellow 

1100 

12 

light blue 

1101 

15 

light magenta 

1110 

13 

light cyan 

1111 

1 

black 


Note: A pixel value of 0 maps to the back¬ 
ground color. 

In addition to the MFDB, Copy Raster also 
takes a rectangle as an argument. This 
allows operations on a specified portion of 
the raster area. A rectangle is specified 
by the x,y coordinates of its upper left and 
lower right vertices. 


COORDINATE SYSTEMS A sample single-plane memory form with a form 

width of 16 pixels, a form height of 8 
pixels, and a highlighted rectangle with 
corners of (3,1) and (6,5) is shown in Figure 
6-3. 
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Coordinate Systems 
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Coordinate Systems 


LOGIC OPERATIONS To provide greatest flexibility, raster 

operations subject to a logic operation take 
the operation as an argument rather than 
using the logic operation associated with 
vector primitives. In addition, the 
operations available are greatly expanded to 
allow more flexibility. Table 6-3 lists the 
available operations with the following con¬ 
ventions: 


o S = pixel value (0 or 1) of source pixel 

o D = pixel value (0 or 1) of destination 
pixel 

o D'= destination pixel value after the logi¬ 
cal operation 


Table 6-3. Raster Operation 
Logic Operations 


Mode 


Definition 

0 

D' = 

0 

1 

D' = 

S AND D 

2 

D' = 

S AND [NOT D] 

3 

D' = 

S 

4 

D' = 

[NOT S] AND D 

5 

D' = 

D 

6 

D' = 

S XOR D 

7 

D' = 

S OR D 

8 

D' = 

NOT [S OR D] 

9 

D' = 

NOT [S XOR D] 

10 

D' = 

NOT D 

11 

D' = 

S OR [NOT D] 

12 

D' = 

NOT S 

13 

D' = 

[NOT S] OR D 

14 

D' = 

NOT [S AND D] 

15 

D' = 

1 


( Replace mode ) 
( Erase mode ) 

( Xor mode ) 
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Logic Operations 


COPY RASTER, 
OPAQUE 


Input 


This function copies a rectangular raster 
area from source form to destination form 
using the logic operation the application 
specifies. If the source and destination 
forms are the same, and the rectangles over¬ 
lap, GEM VDI copies so that the source rec¬ 
tangle is not changed until GEM VDI processes 
the corresponding area in the destination. 
No rotation or transformation occurs as a 
result of this function; the copy is pixel 
for pixel. 

If the source and destination rectangles are 
not the same size, GEM VDI uses the destina¬ 
tion as a pointer and uses the source for the 
size. The Extended Inquire function returns 
scaling ability. The source and destination 
forms must be in device-specific form; see 
"Transform Form" later in this section. 


contr1(0) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 
contrl(7-8) — 


contrl(9-10)- 


Opcode = 109. 

Number of input vertices = 4. 
Length of intin array = 1. 
Device handle. 

Double-word address of the 
source Memory Form Definition 
Block. 

Double-word address of the 
destination Memory Form 

Definition Block. 


intin(0) 

ptsin(O) 
ptsin(1) 
ptsin(2) 

ptsin(3) 


Logic operation (refer to 

"Introduction" in this sec¬ 
tion) . 

x-coordinate of corner of 

source rectangle in RC/NDC. 
y-coordinate of corner of 

source rectangle in RC/NDC. 
x-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(O) of source rec¬ 
tangle in RC/NDC. 
y-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(l) of source rec¬ 
tangle in RC/NDC. 
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Copy Raster, Opaque 


ptsin(4) 
ptsin(5) 
ptsin(6) 


ptsin(7) 


x-coordinate of corner of des¬ 
tination rectangle in RC/NDC. 
y-coordinate of corner of des¬ 
tination rectangle in RC/NDC. 
x-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(4) of destination 
rectangle in RC/NDC. 
y-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(5) of destination 
rectangle in RC/NDC. 


Output contrl(2) -- Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 


C BINDING 
Procedure Name 


vro_cpyfm( handle, wr_mode, 
psrcMFDB, pdesMFDB ) 


pxyarray, 


Data Types 


WORD vro_cpyfm ( ); 

WORD handle; 

WORD wr_mode; 

WORD pxyarray[8]; 
WORD *psrcMFDB; 

WORD *pdesMFDB; 


Input Arguments 


handle = contrl[6] 
wr_mode = intin[0] 
pxyarray[0] = ptsin[0] 
pxyarrayfl] = ptsintl] 


pxyarray[7] = ptsin[7] 
psrcMFDB = contrl[7-8] 
pdesMFDB = contrl[9-103 
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Copy Raster, Opaque 


COPY RASTER, 
TRANSPARENT 

This function copies a monochrome rectangular 
raster area from source form to a color area. 
A writing mode and color indices for both 0's 
and l's are specified in the intin array. 


If the source and destination rectangles are 
not the same size, GEM VDI uses the source 
rectangle for the size and the upper left 
corner of the destination rectangle for the 
initial destination location. 


Transfer of information from the source to 
the destination is controlled by the 
specified writing mode as described below. 
See Table 5-1 for a binding of the available 
writing modes. 

Replace Mode 

Replace mode will result in a replacement of 
all pixels in the destination rectangle. The 
foreground color index specified in intin(1) 
will be output to all pixels associated with 
source locations which are set to a one. The 
background color index specified in intin(2) 
will be output to all pixels associated with 
source locations which are set to a zero. 

Transparent Mode 

Transparent mode only affects the pixels as¬ 
sociated with a source value of one. Those 
pixels are set to the foreground color whose 
index is specified in intin(l). The color 
index specified in intin(2) is not used. 

XOR Mode 

In XOR mode, the monochrome raster source 
area is logically XORed with each plane of 
the destination. The color indices specified 
in intin(l) and intin(2) are not used. 
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Copy Raster, Transparent 


Reverse 

Transparent 

Mode 


Reverse Transparent mode only affects the 
pixels associated with a source value of 
zero. Those pixels are set to the background 
color whose index is specified in intin(2). 
The color index specified in intin(l) is not 
used. 


Input contrl(0) — 

contrl(l) — 
contrl(3) -- 
contrl(6) -- 
contrl(7-8)-- 


contrl(9-10) - 


intin(O) 
intin(l) -- 
intin(2) 

ptsin(O) 

ptsin(l) 

ptsin(2) 


ptsin(3) 


ptsin(4) 

ptsin(5) 

ptsin(6) 


ptsin(7) 


Opcode = 121. 

Number of input vertices = 4. 
Length of intin array = 3. 
Device handle. 

Double-word address of the 
source Memory Form Definition 
Block. 

Double-word address of the 
destination Memory Form 

Definition Block. 

Writing Mode. 

Color index for Is in data. 
Color index for Os in data. 

x-coordinate of corner of 
source rectangle in RC/NDC. 
y-coordinate of corner of 
source rectangle in RC/NDC. 
x-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(O) of source rec¬ 
tangle in RC/NDC. 
y-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(l) of source rec¬ 
tangle in RC/NDC. 

x-coordinate of corner of des¬ 
tination rectangle in RC/NDC. 
y-coordinate of corner of des¬ 
tination rectangle in RC/NDC. 
x-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(4) of destination 
rectangle in RC/NDC. 
y-coordinate of corner diagon¬ 
ally opposite corner selected 
in ptsin(5) of destination 
rectangle in RC/NDC. 
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Copy Raster, Transparent 


Output 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 


contrl(2) -- Number of output vertices = 0. 
contrl(4) — Length of intout array = 0. 


vrt__cpyfm( handle, wr_mode, pxyarray, 
psrcMFDB, pdesMFDB, color_index ) 


WORD vrt_cpyfm ( ); 

WORD handle; 

WORD wr_mode; 

WORD pxyarray[8]; 
WORD *psrcMFDB; 

WORD *pdesMFDB; 

WORD color index[2]; 


handle = contrl[6] 
wr_mode = intin[0] 
pxyarray[0] = ptsin[0] 
pxyarray[l] = ptsin[l] 


• 

pxyarray[7] = ptsin[7] 
psrcMFDB = contrl[7-8] 
pdesMFDB = contrl[9-10] 
color_index[0] = intin[l] 
color index[l] = intin[2] 
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Copy Raster, Transparent 


TRANSFORM FORM This function transforms a raster area from 

standard format to device-specific format or 
from device-specific to standard format. The 
operation is a toggle, changing the current 
state. 

The number of planes specified in the source 
MFDB determines the number transformed. The 
source format flag is toggled and placed in 
the destination. The user is required to en¬ 
sure that the other parameters in the des¬ 
tination MFDB are correct. 


Input contrl(O) -- Opcode = 110. 

contrl(1) — Number of input vertices = 0. 

contrl(3) — Length of intin array = 0. 

contrl(6) — Device handle. 


contrl(7-8) — 

Double-word 
source MFDB. 

address 

of 

the 

contrl(9-10) - 

Double-word 

destination 

address 

MFDB. 

of 

the 


Output contrl(2) -- Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 

Procedure Name vr_trnfm( handle, psrcMFDB, pdesMFDB ) 


Data Types WORD vr_trnfm ( ); 

WORD handle; 

WORD *psrcMFDB; 
WORD *pdesMFDB; 


Input Arguments handle = contrl[6] 

psrcMFDB = contrl[7-8] 
pdesMFDB = contrl[9-10] 
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Get Pixel 


GET PIXEL This function returns a pixel value and a 

color index for the pixel specified by 
ptsin(O), ptsin(l). 

Note: Color index 0 is the background color. 

It may or may not map to pixel value 0 in 
device-specific form. Refer to Tables 6-1 
and 6-2 for the colors and values. Standard 
form always maps color index 0 to pixel value 
0 . 


Input 


contrl(0) 
contr1(1) 
contrl(3) 
contrl(6) 


Opcode = 105. 

Number of input vertices = 1. 
Length of intin array = 0. 
Device handle. 


ptsin(O) 

x-coordinate 
RC/NDC units. 

of 

pixel 

in 

ptsin(l) 

y-coordinate 
RC/NDC units. 

of 

pixel 

in 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 2. 


intout(O) — Pixel value. 
intout(l) -- Color index. 
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Get Pixel 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


v_get_pixel( handle, x, y, &pel, SLindex ) 


WORD v_get_pixel( ); 
WORD handle; 

WORD x; 

WORD y; 

WORD *pel; 

WORD *index; 


handle = contrl[6] 
x = ptsin[0] 
y = ptsin[l] 

pel = intout[0] 
index = intout[1] 


End of Section 6 
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Section 7 INPUT FUNCTIONS 


INTRODUCTION The input functions allow user interactions 

with the application program. Many of the 
input functions support two modes: request 
and sample. In request mode, the driver 
waits until an input event occurs before 
returning. In sample mode, the driver 
returns the current status or location of the 
input device without waiting. 


SET INPUT MODE This function sets the input mode for the 

following specified logical input devices to 
request or sample: 


o locator 
o valuator 
o choice 
o string 


Select the input mode in intin(l). 


Input contrl(O) — Opcode = 33. 

contrl(1) — Number of input vertices = 0. 
contrl(3) — Length of intin array = 2. 

contrl(6) — Device handle. 

intin(O) -- Logical input device. 

1 = locator 

2 = valuator 

3 = choice 

4 = string 

intin(l) — Input mode. 

1 = request 

2 = sample 
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Set Input Mode 


Output 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 1. 


intout(0) 


Input mode selected. 


vsin_mode( handle, dev_type, mode ) 


WORD vsin_mode ( ); 

WORD handle; 

WORD dev_type; 

WORD mode; 


handle = contrl[6] 
dev_type = intin[0] 
mode = intin[l] 
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Input Locator, Request Mode 


INPUT LOCATOR, 
REQUEST MODE 


Input 


This function returns the position of the 
specified locator device. Upon entry to the 
locator routine, the current cursor form is 
displayed at the initial coordinate. The 
graphic cursor is tracked with the input 
device until a terminating event occurs, 
which can result from the user pressing a key 
or a button on a mouse. GEM VDI removes the 
cursor when the terminating event occurs. 
Typically, the arrow keys move the cursor in 
large jumps when used without the Shift key 
and in pixel increments when used with the 
Shift key. 

This function always displays a cursor on the 
screen, even if the cursor is currently 
obscured or hidden. 

Note: If both a keyboard and another locator 
device are available, the cursor is tracked 
by input from either, giving the user maximum 
flexibility. 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 28. 

Number of input vertices = 1. 
Length of intin array = 0. 
Device handle. 


ptsin(O) 

Initial 


x-coordinate 

of 

locator 

in 

NDC/RC units. 


ptsin(l) 

Initial 


y-coordinate 

of 

locator 

in 

NDC/RC units. 
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Input Locator, Request Mode 


Output contrl(2) — 

contrl(4) -- 

intout(O) -- 


ptsout(O) — 
ptsout(l) — 


Number of output vertices = 1. 
Length of intout array = 1. 

Locator terminator. 

The low byte contains a 
character terminator. For 
keyboard-terminated locator 
input, this is the ASCII 
character code of the key 
struck to terminate input. 
For nonkeyboard-terminated in¬ 
put (tablet, mouse, and so 
on), valid locator ter¬ 
minators begin with 20 Hex 
(space) and increase from 
there. For instance, if the 
puck on a tablet has 4 but¬ 
tons, the first button must 
generate a 20 Hex as a ter¬ 
minator, the second a 21 Hex, 
the third a 22 Hex, and the 
fourth a 23 Hex. 

Final x-coordinate of locator 
in NDC/RC units. 

Final y-coordinate of locator 
in NDC/RC units. 
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Input Locator, Request Mode 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Functions 


vrq_locator( handle, x, y, Sxout, Syout, 
&term ) 


WORD vrq_locator ( ); 

WORD handle; 

WORD x, y; 

WORD xout; 

WORD yout; 

WORD term; 


handle = contrl[6] 
x = ptsin[0] 
y = ptsin[l] 


xout = ptsout[0] 
yout = ptsout[l] 
term = intout[0] 
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Input Locator, Sample Mode 


INPUT LOCATOR, This function returns the position in NDCs 
SAMPLE MODE of the specified locator device. Upon entry 

to the locator routine, no cursor is dis¬ 
played. (Use Show Cursor to display the cur¬ 
sor. ) Input is sampled. If the cursor 
position has changed, GEM VDI returns the 
cursor position and contrl(2) is set to 1. 
Contrl(4) is set to 0. If a terminating 
event occurred, GEM VDI returns a character 
and contrl(4) is set to 1. Contrl(2) is set 
to 0. 

Note: If both a keyboard and another locator 
device are available, the input comes from 
either, giving the user maximum flexibility. 


Input 


contrl(O) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 28. 

Number of input vertices = 1. 
Length of intin array = 0. 
Device handle. 


ptsin(0) 
ptsin(1) 


Initial x-coordinate of 

locator in NDC/RC units. 
Initial y-coordinate of 

locator in NDC/RC units. 


Output 


contrl(2) 


contrl(4) 


Number of output vertices. 

1 = coordinate changed 

0 = no coordinate changed 

Length of intout array. 

0 = no keypress character 

1 = keypress character 

returned 
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Input Locator, Sample Mode 


Table 7-1. Sample Mode Status Returned 

Event Control Array 


(2) (4) 

Coordinates change. 1 0 

Key pressed; coordinates 0 1 

not changed from what 
was pressed. 

No input. 0 0 

Key pressed; coordinates 1 1 

changed. 


intout(O) — Locator keypress if keypress 
occurs. 

This information is the same 
as for Input Locator, Request 
Mode function. 

ptsout(O) — New x-coordinate of locator in 
NDC/RC units. 

ptsout(l) — New y-coordinate of locator in 
NDC/RC units. 
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Input Locator, Sample Mode 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


status = vsm_locator( handle, x, y, &xout, 
&yout, &term ) 


WORD status; 

WORD vsm_locator ( ); 

WORD handle; 

WORD x, y; 

WORD xout; 

WORD yout; 

WORD term; 


handle = contrl[6] 
x = ptsin[0] 
y = ptsin[l] 


status = contrl[2] | (contrl[4] << 1) 

xout = ptsout[0] 
yout = ptsout[l] 
term = intout[0] 
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Input Valuator, Request Mode 


INPUT VALUATOR, This function returns the value of the 
REQUEST MODE valuator device. The initial value of the 

valuator is incremented or decremented until 
a terminating character is struck. Valuator 
keys are typically the up-arrow and down-ar¬ 
row keys. Valuator numbers range from 1 to 
100. Typical implementation of the up-arrow 
and down-arrow keys is as follows: 


o Pressing the up-arrow key adds ten to the 
valuator. 

o Pressing the down-arrow key subtracts ten 
from the valuator. 

o Pressing the up-arrow key with the Shift 
key adds one to the valuator. 

o Pressing the down-arrow key with the Shift 
key subtracts one from the valuator. 


Note: This function is not required and may 

not be available on all devices. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 29. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(O) 


Initial value. 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 2. 


intout(O) -- Output value. 

intout(l) — Terminator. 
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Input Valuator, Request Mode 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


vrq_valuator( handle, valuator_in, 
&valuator_out, ^terminator ) 


WORD vrq_valuator ( ); 

WORD handle; 

WORD valuator_in; 

WORD valuator_out; 

WORD terminator; 


handle = contrl[6] 
valuator in = intin[0] 


valuator_out = intout[0] 
terminator = intout[1] 
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Input Valuator, Sample Mode 


INPUT VALUATOR, This function returns the current value of 

SAMPLE MODE the valuator device. The valuator device is 

sampled. If the valuator has changed, GEM 
VDI increments or decrements the valuator 
value as required. If a terminating event 
occurs, GEM VDI returns the value. If 
nothing happens, GEM VDI returns no value. 
Valuator numbers range from 1 to 100. The 
suggested keys are the same as for Input 
Valuator, Request Mode. 

Note: This function is not required and may 

not be available on all devices. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 29. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(0) 


Initial value. 


Output 


contrl(2) 
contrl(4) 


intout(O) 
intout(1) 


Number of output vertices = 0. 
Length of intout array. 

0 = nothing happened 

1 = valuator changed 

2 = keypress character 

New valuator value. 

Keypress, if keypress event 
occurred. 
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Input Valuator, Sample Mode 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


vsm_valuator( handle, val_in, &val_out, 
&term, ^status ) 


WORD vsm_valuator ( ); 

WORD handle; 

WORD val_in; 

WORD val_out; 

WORD term; 

WORD status; 


handle = contrl[6] 
val in = intin[0] 


val_out = intout[0] 
term = intout[1] 
status = contrl[4] 
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Input Choice, Request Mode 


This function returns the choice status of 
the selected choice device. Input is sampled 
until a key is pressed. If it is a valid 
choice key, GEM VDI returns its value. 
Otherwise, GEM VDI returns the initial 
choice number. Choice numbers range from 1 
to a device-dependent maximum value. 

Note: This function is not required and may 
not be available on all devices. 


Input contrl(O) — Opcode = 30. 

contr1(1) — Number of input vertices = 0. 

contrl(3) -- Length of intin array = 1. 

contrl(6) — Device handle. 

intin(O) -- Initial choice number. 


Output contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 1. 

intout(O) — Choice number. 


C BINDING 

Procedure Name vrq_choice( handle, ch_in, &ch_out ) 


Data Types WORD vrq_choice ( ); 

WORD handle; 

WORD ch_in; 

WORD *ch out; 


Input Arguments handle = contrl[6] 

ch in = intin[0] 


Output Arguments *ch_out = intout[0] 


INPUT CHOICE, 
REQUEST MODE 
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Input Choice, Sample Mode 


This function returns the choice status of 
the selected choice device. Upon entry to 
the routine, GEM VDI samples input. If input 
is available and is a valid choice key, GEM 
VDI returns it. Choice numbers range from 1 
to a device-dependent maximum value. 

Note: This function is not required and may 
not be available on all devices. 


Input 

contrl(0) — 
contrl(l) -- 
contrl(3) — 
contrl(6) -- 

Opcode = 30. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Output 

contrl(2) — 
contrl(4) -- 

Number of output vertices = 0. 
Choice status. 



0 = nothing happened 

1 = sample successful 


intout(0) — 

Choice number if sample suc¬ 
cessful, 0 if unsuccessful. 


C BINDING 


Procedure Name status = vsm_choice( handle, Schoice ) 


Data Types WORD status; 

WORD vsm_choice ( ); 

WORD handle; 

WORD choice; 


Input Arguments handle = contrl[6] 


Output Arguments choice = intout[0] 

status = contrl[4] 


INPUT CHOICE, 
SAMPLE MODE 
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Input String, Request Mode 


This function returns a string from the 
specified device. Input is accumulated until 
GEM VDI encounters a carriage return or the 
intout array is full. If the application 
enables echo mode, text will be echoed to 
the screen with the current text attributes 
using the vertex passed in the ptsin array as 
the justification point. 

If the number in intin(O) is negative, the 
values in intout will conform to the standard 
keyboard defined in Appendix D. In this 
case, the absolute value of intin(O) is used 
as the maximum intout size. 

This function will not work if you are using 
the AES! In all request modes it will return 
with no input. 

Note: Echoing of input is not required and 
may not be available on all devices. 


Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 

Opcode = 31. 

Number of input vertices = 1. 
Length of intin array = 2. 
Device handle. 


intin(O) 
intin(1) — 

Maximum string length. 

Echo mode. 



0 = no echo 

1 = echo input characters at 
position specified 


ptsin(O) 

ptsin(1) 

x-coordinate of echo area in 
NDC/RC units. 

y-coordinate of echo area in 
NDC/RC units. 


Output contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array. 


intout — Output string returned in ADE. 


INPUT STRING, 
REQUEST MODE 
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Input String, Request Mode 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


vrq_string( handle, max_length, echo_mode, 
echo_xy, Sstring ) 


WORD vrq_string ( ); 

WORD handle; 

WORD max_length; 

WORD echojmode; 

WORD echo_xy[2]; 

BYTE string[max_length+l]; 


handle = contrl[6] 
max_length = intin[0] 
echo_mode = intin[1] 
echo_x,y = ptsin[0-l] 


string = intout 

Note: The BYTE array elements contain the 
eight least significant bits of the intout 
array elements. The array is terminated with 
a null byte. The length of the output vari¬ 
able string includes an additional byte for 
the terminating null. 
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Input String, Sample Mode 


INPUT STRING, This function returns a string from the 

SAMPLE MODE specified device. Upon entry to the routine, 

GEM VDI samples input. If data is avail¬ 
able, it is accumulated, and GEM VDI samples 
the input again. Input is accumulated until 
one of the following events occurs: 

o Data is no longer available, 
o A carriage return is encountered, 
o The intout buffer is full. 

Note: If the string will always be ter¬ 

minated with RETURN, use Input String, Re¬ 
quest Mode. 

This function will not work if you are using 
the AES! In all request modes it will return 
with no input. 

If the number in intin(O) is negative, the 
values in intout will conform to the standard 
keyboard defined in Appendix D. In this 
case, the absolute value of intin(O) is used 
as the maximum intout size. 


Input contrl( 0 ) — 

contrl(1) — 
contrl(3) — 
contrl(6) — 

intin(0) — 

intin(1) 


ptsin(O) 

ptsin(l) 


Opcode = 31. 

Number of input vertices = 1. 
Length of intin array = 2. 
Device handle. 

Maximum string length. 

Echo mode. 

0 = no echo 

1 = echo input characters 

x-coordinate of echo area in 
NDC/RC units. 

y-coordinate of echo area in 
NDC/RC units. 


Output contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of output string. 

0 = sample unsuccessful 

(characters not available) 
>0 = sample successful 
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Input String, Sample Mode 


intout 


(characters available) 
Output string, if sample 
successful. 
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Input String, Sample Mode 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


status = vsm_string( handle, max_length, 
echo_mode, echo_xy, &string ) 


WORD vsm_string ( ); 

WORD handle; 

WORD max_length; 

WORD echo_mode; 

WORD echo_xy[2]; 

BYTE string[max_length+l]; 
WORD status; 


handle = device handle 
max_length = intin[0] 
echo_mode = intin[l] 
echo_xy = ptsin[0-l] 


string = intout 
status = contrl[4] 

Note: The BYTE array elements contain the 
eight least significant bits of the intout 
array elements. The array is terminated with 
a null byte. The length of the output vari¬ 
able string includes an additional byte for 
the terminating null. 
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Set Mouse Form 


This function redefines the cursor pattern 
displayed during locator input or at any time 
the cursor is shown (see the discussion of 
the Show Cursor function later in this sec¬ 
tion ). 

For the cursor mask and data, bit 15 of word 
1 is the upper left bit of the pattern. Bit 
0 of word 16 is the lower right bit of the 
pattern. Bit zero is the Least Significant 
Bit of the word. 

The hot spot is the location of the pixel 
(relative to the upper left pixel of the 
mouse form) that lies over the pixel whose 
address is returned by the input locator 
function. 

The mouse form is drawn as follows: 

1. The data under the mouse form is saved so 
that it can be restored when the cursor 
moves. 

2. Is in the mask cause the corresponding 
pixel to be set to the color index 
defined in intin(3). 

3. Is in the mouse form data cause the cor¬ 
responding pixel to be set to the color 
index defined in intin(4). 


SET MOUSE 
FORM 


Input Contrl( 0 ) — 

Contrl(1) — 
Contrl(3) — 
Contrl(6) — 

intin(O) 

intin(l) 

intin(2) 

intin(3) 
intin(4) 
intin(5-20)- 
intin(21-36)- 


Opcode = 111. 

Number of input vertices = 0. 
Length of intin array = 37. 
Device Handle. 

x-coordinate of hot spot, 
y-coordinate of hot spot. 

Reserved for future use, must 
be 1. 

Mask color index, normally 0. 
Data color index, normally 1. 

16 words of 16 bit cursor mask. 
16 words of 16 bit cursor data. 
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Set Mouse Form 


Output 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


Contrl(2) — Number of output vertices = 0. 

Contrl(4) -- Length of intout array = 0. 


vsc_form( handle, pcur_form ) 


WORD vsc_form ( ); 

WORD handle; 

WORD pcur_form[37]; 


handle = contrl[6] 
pcur_form[0] = intin[0] 


pcur_form[36] = intin[36] 
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Exchange Timer Interrupt Vector 


EXCHANGE TIMER With this function, the application can 
INTERRUPT VECTOR perform some action each time a timer tick 

occurs. 

The input to this function is a two-word 
pointer in contrl(7) and contrl(8). The 
pointer indicates the starting address of the 
code to receive control when a timer tick oc¬ 
curs. The address of the old timer routine 
is returned in contrl(9) and contrl(10). 

The application-dependent code is invoked 
with a processor-dependent call instruction. 
When this is complete, the application should 
perform a processor-dependent return in¬ 
struction. 

It is the responsibility of the application- 
dependent code to save and restore any 
registers used. 

When the application code is invoked, inter¬ 
rupts are disabled. The application should 
not enable interrupts. 

See Appendix E for processor specific in¬ 
structions and register names. 

The number of milliseconds per timer tick is 
returned in intout(O). 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 
contrl(7-8) - 


Opcode = 118. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Address of application timer 
routine. 


Output 


contrl(2) — 

contrl(4) 
contrl(9-10)- 


Number of output vertices = 0. 
Length of intout array =1. 
Address of the old timer 
routine. 


intout(0) -- Milliseconds per tick. 
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Exchange Timer Interrupt Vector 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


vex_timv( handle, tim_addr, otim_addr, 
&tim_conv ) 


WORD vex_timv( ); 
WORD handle; 

WORD *tim_addr; 
WORD *otim_addr; 
WORD tim conv; 


handle = contrl[6] 
tim addr = contrl[7-8] 


otim_addr = contrl[9-10] 
tim_conv = intout[0] 
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Show Cursor 


SHOW CURSOR This function displays the current cursor. 

The cursor moves on the display surface based 
on information input from a mouse. 

The Show Cursor function and the Hide Cursor 
functions are closely related. Once the cur¬ 
sor is visible, a single Hide Cursor causes 
the cursor to disappear. GEM VDI keeps 
track of the number of times the Hide Cursor 
function is called. The Show Cursor func¬ 
tion must be called the same number of times 
for the cursor to reappear. For example, 
if the Hide Cursor function is called four 
times, the Show Cursor function must be 
called four times for the cursor to appear. 

The Show Cursor function does, however, 
provide a reset flag in intin(O). If in- 
tin(O) is zero, the cursor appears on the 
screen, regardless of the number of Hide 
Cursor calls. A nonzero value for intin(O) 
affects the Show Cursor function as 
described in the preceding paragraph. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 

intin(0) 


Opcode = 122. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 

Reset flag. 

0 = ignore number of Hide 
Cursor calls 

nonzero = normal Show Cursor 
functionality 


Output 


contrl(2) -- Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 
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Show Cursor 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_show_c( handle. 


WORD v_show_c ( ); 

WORD handle; 

WORD reset 


handle = contrl[6] 
reset = intin[0] 


reset ) 
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Hide Cursor 


HIDE CURSOR This function removes the cursor from the 

display surface. This state is the default 
condition set at Open Workstation. The cur¬ 
sor can appear in a new position when the 
application calls the Show Cursor function 
because GEM VDI updates the position based 
on information input from a mouse. 

Refer to the Show Cursor function for a 
description of how the number of Hide Cursor 
calls affects the Show Cursor function. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 123. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 

Procedure Name v_hide_c( handle ) 

Data Types WORD v_hide_c ( ); 

WORD handle; 

Input Arguments handle = contrl[6] 
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Sample Mouse Button State 


SAMPLE MOUSE This function returns the current state of 

BUTTON STATE the mouse buttons. The leftmost mouse but¬ 

ton is returned in the Least Significant Bit 
of the word. A bit value of 1 indicates the 
key is currently depressed; a bit value of 0 
indicates the key is up. 

This function also returns the current (x,y) 
position of the cursor. 


Input 

contrl(0) — 
contrl(1) — 
contrl(3) -- 
contrl(6) — 

Opcode = 124. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 1. 
Length of intout array = 1. 


intout(0) — 

Mouse button state. 


ptsout(O) — 

ptsout(l) — 

x position of cursor in NDC/RC 
units. 

y position of cursor in NDC/RC 
units. 


C BINDING 


Procedure Name vq_mouse( handle, &pstatus, &x, &y ) 


Data Types WORD vq_mouse ( ); 

WORD handle; 

WORD pstatus; 

WORD x, y; 


Input Arguments handle = contrl[6] 


Output Arguments pstatus = intout[0] 

x = ptsout[0] 
y = ptsout[1] 
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Exchange Button Change Vector 


EXCHANGE BUTTON 
CHANGE VECTOR 


Input 


This function allows the application to 
perform some action each time the state of 
the mouse buttons changes. The application 
receives control after the button state is 
decoded, but before the driver button state 
changes. 

The input to this function is a two-word 
pointer in contrl(7) and contrl(8), which 
indicates the starting address of the code to 
receive control when the mouse button state 
changes. Contrl(9) and contrl(10) return a 
two-word pointer to the old mouse routine. 

Control is passed to the specified address 
whenever the mouse button state changes. 
The application code is invoked via a proces¬ 
sor-dependent call instruction with a proces¬ 
sor-dependent register containing the mouse 
button keys. Keys are encoded by the same 
rules that apply to the Sample Mouse Button 
State function. When complete, the ap¬ 
plication-dependent code should do a proces¬ 
sor-dependent return instruction with the 
mouse button state the driver is to store in 
the same register. This gives the application 
the opportunity to alter the buttons before 
they are used by the driver. 

It is the responsibility of the application- 
dependent code to save and restore any 
registers used. 

When the application code is invoked, inter¬ 
rupts are disabled. The application should 
not enable interrupts. 

See Appendix E for processor-specific in¬ 
structions and register names. 


Contrl(O) -- 
Contrl(l) -- 
Contrl(3) -- 
Contrl(6) — 
Contrl(7-8)- 


Opcode = 125. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Address of application mouse 
button state change routine. 
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Exchange Button Change Vector 


Output 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


Contrl(2) — Number of output vertices = 0. 

Contrl(4) -- Length of intout array = 0. 

Contrl(9-10) - Address of old mouse button 
state change routine. 


vex_butv( handle, pusrcode, psavcode ) 


WORD vex_butv ( ); 

WORD handle; 

WORD *pusrcode; 
WORD *psavcode; 


handle = contrl[6] 
pusrcode = contrl[7-8] 


psavcode = contrl[9-10] 
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Exchange Mouse Movement Vector 


This function allows the application to 
perform some action each time the mouse moves 
to a new location. The application receives 
control after the x,y address is computed, 
but before the current mouse position in the 
driver is updated or the mouse form is actu¬ 
ally redrawn on the screen. 

The input to this function is a two-word 
pointer in contrl(7) and contrl(8), which 
indicates the starting address of the code to 
receive control when the mouse moves. A 
two-word pointer to the address of the old 
mouse movement routine is returned in con- 
trl(9) and contrl(10). 

When the mouse moves, the application-depen¬ 
dent code is invoked via a processor-depen¬ 
dent call instruction. The new x and y 
locations are contained in a pair of proces¬ 
sor-dependent registers. Upon completion, 
the application-dependent code should do a 
processor-dependent return instruction with 
the x,y mouse position the driver is to store 
in the appropriate hardware registers. This 
procedure gives the opportunity to alter the 
x,y position before it is used by the driver. 

It is the responsibility of the application- 
dependent code to save and restore any 
registers used. 

When the application code is invoked, inter¬ 
rupts are disabled. The application should 
not enable interrupts. 

See Appendix E for processor-specific in¬ 
structions and register names. 


EXCHANGE MOUSE 
MOVEMENT VECTOR 


7-30 



GEM VDI 

Programmer's Guide 

Exchange 

Mouse Movement Vector 

Input 

Contrl(O) — 
Contrl(l) — 
Contrl(3) — 
Contrl(6) -- 
Contrl(7-8)- 

Opcode = 126. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Address of application mouse 
movement routine. 

Output 

Contrl(2) -- 
Contrl(4) -- 
Contrl(9-10) 

Number of 
Length of 
- Address 
movement 

output vertices = 0. 
intout array = 0. 
of the old mouse 

routine. 


C BINDING 

Procedure Name vex_motv( handle, pusrcode, psavcode ) 


Data Types WORD vex_motv ( ); 

WORD handle; 

WORD *pusrcode; 
WORD *psavcode; 


Input Arguments handle = contrl[6] 

pusrcode = contrl[7-8] 

Output Arguments psavcode = contrl[9-10] 
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Exchange Cursor Change Vector 


EXCHANGE CURSOR 
CHANGE VECTOR 


This function allows the application to 
perform some action each time the cursor is 
drawn. The application can completely take 
over drawing the cursor or can perform some 
action and have GEM VDI draw the cursor. 
Control is passed to the application whenever 
the cursor position should be updated. 

The input to this function is a two-word 
pointer in contrl(7) and contrl(8), which 
indicates the starting address of the code to 
receive control when a cursor is drawn. 
The address of the old cursor draw routine is 
returned in contrl(9) and contrl(10). 

The application-dependent code is invoked 
with a processor-dependent call instruction. 
The x,y position at which the cursor should 
be drawn is contained in a pair of proces¬ 
sor-dependent registers. If the application- 
dependent code does not draw its own cursor, 
a processor-dependent call should be per¬ 
formed to the address returned in contrl(9) 
and contrl(10). This will cause GEM VDI to 
draw a cursor. When it is done, the applica¬ 
tion should perform a processor-dependent 
return instruction. 

It is the responsibility of the application- 
dependent code to save and restore any 
registers used. The GEM VDI cursor draw 
routine preserves the contents of all 
registers. 

When the application code is invoked, inter¬ 
rupts are disabled. The application should 
not enable interrupts. 

See Appendix E for processor-specific in¬ 
structions and register names. 
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Exchange Cursor Change Vector 


Input 

Output 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 
contrl(7-8)- 


Opcode = 127. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Address of application cursor 
draw routine. 


contrl(2) — Number of output vertices = 0 

contrl(4) -- Length of intout array = 0 

contrl(9-10) - Address of the old cursor draw 
routine. 


vex_curv( handle, pusrcode, psavcode ) 


WORD vex_curv ( ); 

WORD handle; 

WORD *pusrcode; 
WORD *psavcode; 


handle = contrl[6] 
pusrcode = contrl[7-8] 


psavcode = contrl[9-10] 
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Sample Keyboard State Information 


SAMPLE KEYBOARD 
STATE INFORMATION 

This function returns the current state of 
the keyboard's Control, Shift, and Alt keys. 
These values are returned as a bit-encoded 
value in intout(O). The keys are assigned to 
bits as follows: 


Bit 0 - right Shift Key 

Bit 1 - left Shift Key 

Bit 2 - Control Key 

Bit 3 - Alt Key 


Bit 0 is the Least Significant Bit of the 
word. A bit value of zero indicates the key 
is up, a bit value of 1 indicates the key is 
depressed. 

Input 

contrl(O) — 
contrl(1) — 
contrl(3) — 
contrl(6) — 

Opcode = 128. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 1. 


intout(O) -- 

Keyboard state. 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 
Output Arguments 


vq_key_s( handle, Spstatus ) 

WORD vq_key_s ( ); 

WORD handle; 

WORD pstatus; 

handle = contrl[6] 

pstatus = intout[0] 


End of Section 7 
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Section 8 
INQUIRE FUNCTIONS 


INTRODUCTION Inquire functions return the current settings 

for device-specific attributes. 


EXTENDED INQUIRE This function returns additional device¬ 
specific information not included in the 
Open Workstation call. The value of intin(O) 
determines if GEM VDI returns the values 
returned at Open Workstation or an extended 
set of device-specific information. Refer 
to Section 3, "Control Functions," for more 
information about intout values for the Open 
Workstation function. 

Note that 6 vertices and 45 intouts are al¬ 
ways returned, although some values are un¬ 
defined for the extended device information. 


Input contrl(O) — Opcode = 102. 

contrl(l) -- Number of input vertices = 0. 

contrl(3) -- Length of intin array = 1. 

contrl(6) — Device handle. 

intin(O) -- Information type. 

0 = Open Workstation values 
1 = Extended Inquire values 
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Extended Inquire 


Output contrl(2) -- 

contrl(4) — 

intout(0) — 


intout(l) -- 


intout(2) — 

intout(3) -- 

intout(4) — 
intout(5) -- 

intout(6) -- 

intout(7) -- 
intout(8) -- 


Number of output vertices = 6. 
Length of intout array = 45. 

Type of screen. 

0 -- not screen 

1 — separate alpha and 

graphic controllers and 
separate video screens 

2 — separate alpha and 

graphic controllers with 
a common video screen 

3 — common alpha and graphic 

controller with separate 
image memory 

4 — common alpha and graphic 

controller with common 
image memory 

Number of background colors 
available in color palette. 

On some devices this may be 
different from the number of 
colors returned from Open 
Workstation, intout(39). 

Text effects supported. 

(See "Set Graphic Text Special 
Effects" in Section 5 for 
values.) 

Scale rasters. 

0 = scaling not possible 
1 = scaling possible 

Number of planes. 

Lookup table supported. 

0 = table supported 
1 = table not supported 

Performance factor, number of 
16 x 16 pixel raster ops per 
second. 

Contour fill capability. 
Character rotation ability. 

0 = none 

1 = 90-degree increments only 

2 = arbitrary angles 
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Extended Inquire 


intout(9) — 
intout(10)— 

intout(11)-- 

intout(12)-- 

intout(13)-- 

intout(14)— 

intout(15) — 

intout(16)— 
intout(17)— 

intout(18)— 
intout(19-44)- 

ptsout(0-11) 


Number of writing modes avail¬ 
able. 

Highest level of input mode 
available. 

0 = none 

1 = request 

2 = sample 

Text alignment capability 

flag. 

0 = no 
1 - yes 

Inking capability flag. 

0 = device cannot ink 
1 = device can ink 

Rubberbanding capability flag. 

0 = no 

1 = capable of rubberband 

lines 

2 = capable of both rubberband 

lines and rectangles 

Maximum vertices for Polyline, 
Polymarker, or Filled Area. 

-1 = no maximum 

Maximum intin. 

-1 = no maximum 

Number of keys available on 
the mouse. 

Styles for wide lines. 

0 = no 
1 = yes 

Writing modes for wide lines. 
Reserved, contains zeros. 

Reserved, contains zeros. 
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Extended Inquire 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


vq_extnd( handle, owflag, work_out ) 


WORD vq_extnd ( ); 

WORD handle; 

WORD owflag; 

WORD work out[57] 


handle = contrl[6] 
owflag = intin[0] 


work out[0] = intout[0] 


work_out[44] = intout[44] 
work_out[45] = ptsout[0] 

work_out[56] = ptsout[ll] 
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Inquire Color Representation 


INQUIRE COLOR This function returns either the requested or 

REPRESENTATION the actual value of the specified color index 

in RGB units. Both the set and realized 
values are available. If the selected index 
is out of range, GEM VDI returns -1 in in¬ 
tout (0). 

Here are some useful formulas for Atari ST 
RGB color conversion: 

from hardware to VDI: VDI=(HDW*125)+62 

from VDI to hardware: HDW=VDI/142 


Input contrl(O) -- Opcode = 26. 

contrl(l) -- Number of input vertices = 0. 
contrl(3) --- Length of intin array = 2. 

contrl(6) — Device handle. 

intin(O) — Requested color index. 

intin(l) — Set or realized flag. 

0 = set (return color values 
requested) 

1 = realized (return color 
values realized on device) 


Output contrl(2) -- Number of output vertices = 0. 

contrl(4) -- Length of intout array = 4. 

intout(O) — Color index. 

intout(l) -- Red intensity (in tenths of 

percent 0-1000). 
intout(2) — Green intensity. 

intout(3) — Blue intensity. 
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Inquire Color Representation 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


vq_color( handle, color_index, set_flag, rgb ) 


WORD vq_color ( ); 

WORD handle; 

WORD color_index; 
WORD setflag; 

WORD rgb[3]; 


handle = contrl[6] 
color_index = intin[0] 
set_flag = intin[l] 


rgb[0] = intout[1] 
rgb[l] = intout[2] 
rgb[2] = intout[3] 
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Inquire Polyline Attributes 


INQUIRE CURRENT 

POLYLINE 

ATTRIBUTES 

This function reports the current setting of 
all attributes that affect polylines, such as 
line type, line color, line width, end 
styles, and writing mode. 

Input 

contrl(0) — 
contrl(l) -- 
contrl(3) — 
contrl(6) — 

Opcode = 35. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 

Output 

contrl(2) -- 
contrl(4) -- 

Number of output vertices = 1. 
Length of intout array = 5. 


intout(O) — 

Current polyline line type. 



(Refer to Set Polyline Line 
Type function.) 


intout(1) — 

intout(2) — 

Current polyline line color 
index. 

Current writing mode. 



(Refer to the Set Writing Mode 
function.) 


intout(3) — 

intout(4) — 

ptsout(0) — 

ptsout(l) — 

End style for beginning point 
of polyline. 

End style for ending point of 
polyline. 

Current line width, in current 
coordinate system. 

0. 


8-7 




GEM VDI Programmer's Guide 


Inquire Polyline Attributes 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 
Output Arguments 


vql_attributes( handle. 


WORD vql_attributes ( ) 

WORD handle; 

WORD attrib[4]; 


handle = contrl[6] 


attrib[0] = intout[0] 
attrib[l] = intout[1] 
attrib[2] = intout[2] 
attrib[3] = ptsout[0] 


attrib ) 
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Inquire Polymarker Attributes 


INQUIRE CURRENT 

POLYMARKER 

ATTRIBUTES 


This function reports the current setting of 
all attributes that affect polymarkers, such 
as marker type, marker color, marker height, 
and writing mode. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 36. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 


Output contrl(2) 

contrl(4) 

intout(0) 

intout(1) 
intout(2) 

ptsout(O) 
ptsout(1) 


Number of output vertices = 1. 
Length of intout array = 3. 

Current polymarker marker 

type. 

(Refer to Set Polymarker Type 
function.) 

Current polymarker marker 

color index. 

Current writing mode. 

(Refer to the Set Writing Mode 
function for description.) 

Current polymarker width, in 
current coordinate system. 
Current polymarker height, in 
current coordinate system. 
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Inquire Polymarker Attributes 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 
Output Arguments 


vqm_attributes( handle. 


WORD vqm_attributes ( ) 

WORD handle; 

WORD attrib[4]; 


handle = contrl[6] 


attrib[0] = intout[0] 
attrib[l] = intout[1] 
attrib[2] = intout[2] 
attrib[3] = ptsout[l] 


attrib ) 
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Inquire Fill Area Attributes 


INQUIRE CURRENT 
FILL AREA 
ATTRIBUTES 


This function reports the current setting of 
all attributes that affect fill areas, such 
as interior style, fill color, fill style in¬ 
dex, and writing mode. 


Input contrl(O) — Opcode = 37. 

contrl(1) — Number of input vertices = 0. 
contrl(3) — Length of intin array = 0. 
contrl(6) -- Device handle. 


Output 


contrl(4) -- Number of output vertices = 0. 
contrl(6) -- Length of intout array = 5. 

intout(O) — Current fill area interior 
style. 

(Refer to Set Fill Interior 
Style function.) 

intout(l) — Current fill area color index. 
intout(2) — Current fill area style index. 

(Refer to Set Fill Style Index 
function.) 


intout(3) — Current writing mode. 

(Refer to the Set Writing Mode 
function.) 


intout(4) — Current fill perimeter status. 
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Inquire Fill Area Attributes 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 
Output Arguments 


vqf_attributes( handle. 


WORD vqf_attributes( ); 

WORD handle; 

WORD attrib[4]; 


handle = contrl[6] 


attrib[0] = intout[0] 
attrib[l] = intout[1] 
attrib[2] = intout[2] 
attrib[3] = intout[3] 


attrib ) 
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Inquire Fill Area Attributes 


INQUIRE CURRENT 
GRAPHIC TEXT 
ATTRIBUTES 


This function returns the current setting of 
all attributes that affect graphic text, such 
as text size, text color, text face align¬ 
ment, baseline rotation, and writing mode. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 38. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 


Output contrl(2) -- 

contrl(4) — 

intout(O) — 
intout(l) -- 

intout(2) — 
intout(3) — 

intout(4) -- 

intout(5) — 

ptsout(O) — 
ptsout(l) — 
ptsout(2) -- 
ptsout(3) — 


Number of output vertices = 2. 
Length of intout = 6. 

Current graphic text face. 
Current graphic text color in¬ 
dex. 

Current angle of rotation of 
text baseline (in tenths of 
degrees 0-3600). 

Current horizontal alignment. 

(Refer to Set Graphic Text 
Alignment function.) 

Current vertical alignment. 

(Refer to Set Graphic Text 
Alignment function.) 

Current writing mode. 

(Refer to the Set Writing Mode 
function.) 

Current character width in 
current coordinate system. 
Current character height in 
current coordinate system. 
Current character cell width 
in current coordinate system. 
Current character cell height 
in current coordinate system. 
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Inquire Graphic Text: Attributes 


C BINDING 

Procedure Name vqt_attributes( handle. 


Data Types WORD vqt_attributes ( ) 

WORD handle; 

WORD attrib[10]; 


Input Arguments handle = contrl[6] 

Output Arguments attrib[0] = intout[0] 

attribCl] = intout[1] 


attrib[5] = intout[5] 
attrib[6] = ptsout[0] 

attrib[9] = ptsout[3] 


attrib ) 
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Inquire Text Extent 


INQUIRE 

EXTENT 


Input 


TEXT This function returns a rectangle that 

encloses the requested string. The coor¬ 
dinates of the vertices are given relative 
to a coordinate system defined such that the 
extent rectangle touches both the x and y 
axes, and the string is in the first quad¬ 
rant. All text attributes, including style 
and baseline rotation, affect the calcula¬ 
tion. 


X-axis 



Y-axis 


Figure 8-1. 


Inquire Text Extent Function 


contr1(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 116. 

Number of input vertices = 0. 
Number of words in text. 
Device handle. 


intin 


Character string in current 
character set. 
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Inquire Text Extent 


Output 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


contrl(2) — 

Number 

of output vertices 

« 4. 

contrl(4) — 

Length of intout array = 

0 . 

ptsout(O) — 

delta-x 

for point 

1 of 

the 


string 

in the current 

coor- 


dinate 

system. 



ptsout(l) -- 

delta-y 

for point 

1 of 

the 


string 

in the current 

coor- 


dinate 

system. 



ptsout(2) -- 

delta-x 

for point 

2 of 

the 


string 

in the current 

coor- 


dinate 

system. 



ptsout(3) — 

delta-y 

for point 

2 of 

the 


string 

in the current 

coor- 


dinate 

system. 



ptsout(4) — 

delta-x 

for point 

3 of 

the 


string 

in the current 

coor- 


dinate 

system. 



ptsout(5) — 

delta-y 

for point 

3 of 

the 


string 

in the current 

coor- 


dinate 

system. 



ptsout(6) — 

delta-x 

for point 

4 of 

the 


string 

in the current 

coor- 


dinate 

system. 



ptsout(7) — 

delta-y 

for point 

4 of 

the 


string 

in the current 

coor- 


dinate 

system. 




vqt_extent( handle, string, extent ) 


WORD vqt_extent( ); 
WORD handle; 

WORD extent[8]; 

BYTE string[]; 


handle = contrl[6] 
string = intin 


extent[0] = ptsout[0] 


extent[7] 


ptsout[7] 
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Inquire Character Cell Width 


INQUIRE CHARACTER 
CELL WIDTH 


Input 


This function returns the character cell 
width for a specified character in the cur¬ 
rent text face. The character cell width is 
the distance from the left edge of the 
character to the left edge of the character 
that follows it in a text string. Special 
effects and rotation do not apply. GEM VDI 
returns all values in the current coordinate 
system. 


Left Character 
Alignment 
Delta 


Right Character 

Alignment 

Data 


W 

Character 

Width 

- Cell Width - 


T 


Character 

Height 

i Cell Height 


Figure 8-2. Character Cell Definition 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 117. 

Number of input vertices = 0. 
Length of intin array = 1. 
Device handle. 


intin(0) 


Character value in current 
character set in ADE format. 
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Inquire Character Cell Width 


Output 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 

Output Arguments 


contrl(2) -- 

Number 

of output vertices = 3. 

contrl(4) -- 

Length 

of intout array = 1. 

intout(O) -- 

ADE value of the 

character 


being 

inquired on; 

-1 if an 


invalid character (status). 

ptsout(O) -- 

Cell width of the character in 
the current coordinate system. 

ptsout(l) -- 

0 . 



ptsout(2) -- 

Left 

delta. 

character 

alignment 

ptsout(3) — 

0 . 



ptsout(4) — 

Right 

delta. 

character 

alignment 

ptsout(5) -- 

0 . 




status = vqt_width( handle, character, 

&cell_width, &left_delta, &right_delta ) 


WORD status; 

WORD vqt_width( ); 
WORD handle; 

BYTE character; 
WORD cell_width; 
WORD leftdelta; 
WORD right_delta; 


handle = contrl[6] 
character = intin[0] 


status = intout[0] 
cell_width = ptsout[0] 
left_delta = ptsout[2] 
right_delta = ptsout[4] 
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Inquire Face Name and Index 


INQUIRE FACE NAME This function returns a 32-character string 
AND INDEX that describes the face. The face is 

selected by its element number (1 to the num¬ 
ber of faces available). One word of zero 
in the intin array terminates the string. 

The string describing the face is returned in 
ADE form in intout(1... 32). The face ID to 
access this face with Set Text Face is 
returned in intout(l). The first 16 charac¬ 
ters name the face. The next 16 characters 
describe the style and weight. See Table 8- 
1 for a sample of the possible con¬ 
figurations . 

Note : The return value of -1 indicates a 
dummy font which should be skipped. 


Table 8-1. Face Names and Styles 


Face Name 


Styles 


Swiss 721 
Swiss 721 
Dutch 801 
Dutch 801 


Light 

Thin Italic 
Roman 

Bold Italic 


Input 

contrl(O) -- 
contrl(l) — 
contrl(3) -- 
contrl(6) -- 

Opcode = 130. 
Number of input 
Length of intin 
Device handle. 

vertices = 0 
array = 1 . 


intin(O) 

Element number. 



Output 

contrl(2) -- 
contrl(4) — 

Number of output 
Length of intout 

vertices = 0 
array = 33. 


intout(0) — 
intout(l) to 
intout(32) - 

ID number. 

32 ADE. 
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Inquire Face Name and Index 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 

Output Arguments 


index = vqt_name( handle, element_num, name ) 


WORD index; 

WORD vqt_name( ); 

WORD handle; 

WORD element_num, 
BYTE name[32]; 


handle = contr[6] 
element num = intin[0] 


index = intout[0] 
name[0] = intout[1] 


name[31] = intout[32] 


Note: The BYTE array elements contain the 
eight least significant bits of the intout 
array elements. The array is terminated with 
a null byte. 
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Inquire Current Face Information 


INQUIRE CURRENT This function returns size information for 
FACE INFORMATION the current face with the current size and 

special effects. Because the special effects 
may change the cell width and extent, a 
value is returned to allow the use of the 
width information returned in Inquire 
Character Cell Width. When the character is 
skewed, the cell contains left and right of¬ 
fsets as shown in Figure 8-3. 


Character 

Positio 


Left Offset 



Right Offset 


Figure 8-3. Right and Left Offset 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(6) 


Opcode = 131. 

Number of input vertices = 0. 
Length of intin array = 0. 
Device handle. 


Output contrl(2) — 

contrl(4) — 

intout(0) -- 

intout(l) -- 

ptsout(O) -- 
ptsout(l) — 
ptsout(2) — 


Number of output vertices = 5. 
Length of output array = 2. 

Minimum ADE (ASCII Decimal 
Equivalent) the first charac¬ 
ter in this face. 

Maximum ADE, the last charac¬ 
ter in this face. 

Maximum cell width not in¬ 
cluding special effects. 

Bottom line distance relative 
to baseline. 

Special effects delta x. The 
current special effects in¬ 
crease character width by 
this amount. 
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Inquire Current Face Information 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 
Output Arguments 


ptsout(3) — 

Descent line distance relative 


to baseline. 



ptsout(4) — 

Left offset; (see Figure 

8- 


2) positive value 
position. 

relative 

to 

ptsout(5) -- 

Half distance 

baseline. 

relative 

to 

ptsout(6) -- 

Right offset (see 

Figure 8- 

2). 

ptsout(7) — 

Ascent distance 
baseline. 

relative 

to 

ptsout(8) — 

0 . 



ptsout(9) — 

Top distance 

baseline. 

relative 

to 


vqt_fontinfo( handle, SminADE, SmaxADE, 
distances, &maxwidth, effects ) 


WORD vqt_fontinfo( ); 
WORD handle; 

WORD minADE; 

WORD maxADE; 

WORD distances[5] ; 
WORD maxwidth; 

WORD effects[3]; 


handle = contrl[6] 


minADE = intout[0] 
maxADE = intout[1] 
distances[0] = ptsout[l] 
distances[1] = ptsout[3] 
distances[2] = ptsout[5] 
distances[3] = ptsout[7] 
distances[4] = ptsout[9] 
maxwidth = ptsout[0] 
effects[0] = ptsout[2] 
effects[l] = ptsout[4] 
effects[2] = ptsout[6] 
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Inquire Cell Array 


INQUIRE CELL ARRAY This function returns the cell array defini¬ 
tion of the specified pixels. Color indices 
are returned one row at a time, starting from 
the top of the rectangular area, proceeding 
downward. 

Note: This function is not required and may 

not be available on all devices. 


Input contrl(0) — 

contrl(1) — 
contrl(3) — 
contrl(6) — 
contrl(7) -- 

contrl(8) — 


ptsin(O) 


ptsin(1) 


ptsin(2) 


ptsin(3) 


Opcode = 27. 

Number of input vertices = 2. 
Length of intin array = 0. 
Device handle. 

Length of each row in color 
index array. 

Number of rows in color index 
array. 

x-coordinate of lower left 
corner in current coordinate 
system. 

y-coordinate of lower left 
corner in current coordinate 
system. 

x-coordinate of upper right 
corner in current coordinate 
system. 

y-coordinate of upper right 
corner in current coordinate 
system. 


Output contrl(2) 

contrl(4) 

contrl(9) 

contrl(10) 

contrl(11) 


Number of output vertices = 0. 
Length of the color index ar¬ 
ray, same as contrl(3). 

Number of elements used in 
each row of color index array. 
Number of rows used in color 
index array. 

Invalid value flag. 

0 — if no errors 
1 -- if a color value could 
not be determined for 
some pixel 
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Inquire Cell Array 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 


Output Arguments 


intout — Color index array, stored one 
row at time. 

-1 -- indicates that a color 
index could not be 
determined for that 
particular pixel 


vq_cellarray( handle, pxyarray, row_length, 
num_rows, &el_used, 6rows_used, &status, 
colarray ) 


WORD vq_cellarray( ); 
WORD handle; 

WORD pxyarray[ 4 ] ; 

WORD row_length; 

WORD num_rows; 

WORD el_used; 

WORD rows_used; 

WORD status; 

WORD colarray[n]; 


handle = contrl[6] 
pxyarray[0] = ptsin[0] 
pxyarray[l] = ptsin[l] 
pxyarray[2] = ptsin[2] 
pxyarray[3] = ptsin[3] 
row_length = contrl[7] 
num rows = contrl[8] 


elused = contrl[9] 
rows_used = contrl[10] 
status = contrl[ll] 
colarray[0] = intout[0] 


colarray[n] = intin[n] 
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Inquire Input Mode 


INQUIRE INPUT MODE 

This function returns the current input mode 
for the specified logical input device: 
locator, valuator, choice, and string. 

Input 

contrl(0) 

_ _ 

Opcode = 115. 


contrl(1) 

-- 

Number of input vertices = 0. 


contrl(3) 


Length of intin array = 1. 


contrl(6) 

— 

Device handle. 


intin(0) 


Logical input device. 

1 = locator 

2 = valuator 

3 = choice 

4 = string 


Output 

contrl(2) — 
contrl(4) — 

Number of output 
Length of intout 

vertices = 0. 
array = 1. 


intout( 0 ) — 

Input mode. 




1 = request 

2 = sample 



C BINDING 

Procedure Name vqin_mode( handle, dev_type, &input_mode ) 


Data Types WORD vqin_mode( ); 

WORD handle; 

WORD dev_type; 

WORD input_mode; 


Input Arguments handle = contrl[6] 

dev_type = intin[0] 

Output Arguments input_mode = intout[0] 


End of Section 8 
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Section 


ESCAPE 


Input 


ESCAPES 


The Escape function allows the application 
program to access the special capabilities 
of a graphics device. GEM VDI predefines 
some escape functions; others can be defined 
for specific devices. The parameters passed 
depend on the escape function the applica¬ 
tion requests. 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 


Opcode = 5. 

Number of input vertices. 
Number of input parameters. 
Function identifier (id). 
Device handle. 


Table 9-1. Escape Function Identifiers 
Number Description 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 
11 
12 

13 


INQUIRE ADDRESSABLE ALPHA 
CHARACTER CELLS 

EXIT ALPHA MODE 

ENTER ALPHA MODE 

ALPHA CURSOR UP 

ALPHA CURSOR DOWN 

ALPHA CURSOR RIGHT 

ALPHA CURSOR LEFT 

HOME ALPHA CURSOR 

ERASE TO END OF ALPHA SCREEN 

ERASE TO END OF ALPHA TEXT LINE 

DIRECT ALPHA CURSOR ADDRESS 

OUTPUT CURSOR ADDRESSABLE ALPHA 
TEXT 

REVERSE VIDEO ON 
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Escapes 


Number 

14 

15 

16 

17 

18 

19 

20 
21 
22 
23 

24-59 

60 

61-90 

91 

92 

93 

94 

95 

96 

98 

99 

100 
>100 


Table 9-1. (continued) 

Description 

REVERSE VIDEO OFF 

INQUIRE CURRENT ALPHA CURSOR 
ADDRESS 

INQUIRE TABLET STATUS 
HARD COPY 

PLACE GRAPHIC CURSOR AT 
LOCATION 

REMOVE LAST GRAPHIC CURSOR 

FORM ADVANCE 

OUTPUT WINDOW 

CLEAR DISPLAY LIST 

OUTPUT BIT IMAGE FILE 

UNUSED BUT RESERVED FOR FUTURE 
EXPANSION 

SELECT PALETTE 

UNUSED BUT RESERVED FOR FUTURE 
EXPANSION 

INQUIRE PALETTE FILM TYPES 
INQUIRE PALETTE DRIVER STATE 
SET PALETTE DRIVER STATE 
SAVE PALETTE DRIVER STATE 
SUPPRESS PALETTE MESSAGES 
PALETTE ERROR INQUIRE 
UPDATE METAFILE EXTENTS 
WRITE METAFILE ITEM 
CHANGE GEM VDI FILENAME 
UNUSED AND AVAILABLE FOR USE 
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Escapes 


intin -- Function-dependent information 

described on following pages. 

ptsin -- Array of input coordinates for 

escape function. 


Output 

contrl(2) -- 
contrl(4) -- 

Number 

Number 

of output vertices, 
of output parameters 


intout 

Array 

of output parameters. 


ptsout 

Array 

of output coordinates 
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Escapes 

ESCAPE 1 : INQUIRE 
ADDRESSABLE ALPHA 
CHARACTER CELLS 

This escape returns information to the 
calling program about the number of vertical 
(row) and horizontal (column) positions at 
which the alpha cursor can be positioned on 
the screen. Typically, only screens support 
alpha text. 

Input 

contrl(0) — 
contr1(1) — 
contrl(3) — 
contrl(5) -- 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 

Length of intin array = 0. 

Function id = 1. 

Device handle. 

Output 

contrl(2) -- 
contrl(4) — 

Number of output vertices = 0. 

Length of intout array = 2. 


intout(O) -- 

intout(l) -- 

Number of addressable rows on 
the screen, (-1 indicates 
cursor addressing not pos¬ 
sible) . 

Number of addressable columns 
on the screen, (-1 indicates 
cursor addressing not pos¬ 
sible ). 


C BINDING 


Procedure Name vq_chcells( handle, &rows, ^columns ) 


Data Types WORD vq_chcells ( ); 

WORD handle; 

WORD rows; 

WORD columns; 


Input Arguments handle = contrl[6] 


Output Arguments rows = intout[0] 

columns = intout[1] 
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Inquire Addressable Character Cells 


ESCAPE 2 : EXIT 
ALPHA MODE 

This escape causes the graphics device to 
enter graphics mode if graphics mode is dif¬ 
ferent from alpha mode. It is used to exit 
alpha cursor addressing mode explicitly and 
to make the transition from alpha to 
graphics mode properly. 

Input 

contrl(O) — 
contrl(1) — 
contrl(3) — 
contrl(5) — 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 2. 

Device handle. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 

C BINDING 



Procedure Name 

v_exit_cur( handle ) 


Data Types WORD v_exit_cur ( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Exit Alpha Mode 


ESCAPE 3 : ENTER 
ALPHA MODE 

This escape causes the graphics device to 
exit graphics mode if graphics mode is dif¬ 
ferent from alpha mode. It is used to enter 
the alpha cursor addressing mode explicitly 
and to make the transition from graphics to 
alpha mode properly. This opcode also 
returns the cursor to the upper left charac¬ 
ter cell of the display device. 

Input 

contrl(0) — 
contrl(l) -- 
contrl(3) -- 
contrl(5) -- 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 3. 

Device handle. 

Output 

contrl(2) — 
contrl(4 ) — 

Number of output vertices = 0. 
Length of intout array = 0. 

C BINDING 



Procedure Name 

v_enter_cur( 

handle ) 


Data Types WORD v_enter_cur ( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Enter Alpha Mode 


ESCAPE 

CURSOR 

4: ALPHA 

UP 

This escape moves the alpha cursor up one row 
without altering its horizontal position. 
If the cursor is already at the top margin, 
nothing happens. 

Input 


contrl(O) -- 
contrl(l) -- 
contrl(3) — 
contrl(5) -- 
contrl( 6 ) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 4. 

Device handle. 

Output 


contrl( 2 ) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_curup( handle ) 

WORD v_curup ( ); 

WORD handle; 

handle = contrl[6] 
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Alpha Cursor Up 


ESCAPE 

CURSOR 

5 : ALPHA 

DOWN 

This escape moves the alpha cursor down one 
row without altering its horizontal position. 
If the cursor is already at the bottom mar¬ 
gin, nothing happens. 

Input 


contrl(0) — 
contrl(l) -- 
contrl(3) — 
contrl(5) — 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 5. 

Device handle. 

Output 


contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 


C BINDING 

Procedure Name v_curdown( handle ) 

Data Types WORD v_curdown ( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Alpha Cursor Down 


ESCAPE 6: ALPHA The Alpha Cursor Right escape moves the alpha 
CURSOR RIGHT cursor right one column without altering its 

vertical position. If the cursor is already 
at the right margin, nothing happens. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 


Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 6. 

Device handle. 


Output 


contrl(2) -- Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_curright( handle ) 

WORD v_curright ( ); 

WORD handle; 

handle = contrl[6] 
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Alpha Cursor Right 


ESCAPE 

CURSOR 

7: ALPHA 

LEFT 

The Alpha Cursor Left escape moves the alpha 
cursor left one column without altering its 
vertical position. If the cursor is already 
at the left margin, nothing happens. 

Input 


contrl(0) — 
contrl(l) -- 
contrl(3) -- 
contrl(5) 
contrl( 6 ) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 7. 

Device handle. 

Output 


contrl (2) — 
contrl( 4 ) — 

Number of output vertices = 0. 
Length of intout array = 0. 


C BINDING 

Procedure Name v_curleft( handle ) 

Data Types WORD v_curleft ( ); 

WORD handle; 

Input Arguments handle = contrl[6] 
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Alpha Cursor Left 


ESCAPE 8: HOME 
ALPHA CURSOR 

This escape moves the alpha cursor to the 
home position, usually the upper left charac¬ 
ter cell of the display device. 

Input 

contrl(0) — 
contrl(l) -- 
contrl(3) -- 
contrl( 5 ) — 
contrl(6) -- 

Opcode = 5 . 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 8. 

Device handle. 

Output 

contrl(2) -- 
contrl(4) -- 

Number of output vertices = 0. 
Length of intout array = 0. 

C BINDING 



Procedure Name 

v_curhome( handle ) 

Data Types 

WORD v curhome 
WORD handle; 

( )? 


Input Arguments 


handle = contrl[6] 
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Home Alpha Cursor 


ESCAPE 9: ERASE 
TO END OF ALPHA 
SCREEN 


This escape erases the display surface from 
the current alpha cursor position to the end 
of the alpha screen. The current alpha cur¬ 
sor location does not change. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 


Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 9. 

Device handle. 


Output 


contrl(2) -- Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_eeos( handle ) 

WORD v_eeos ( ); 

WORD handle; 

handle = contrl[6] 
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Erase to End of Alpha Screen 


ESCAPE 10: ERASE 
TO END OF ALPHA 
TEXT LINE 

This escape erases the display surface from 
the current alpha cursor position to the end 
of the current alpha text line. The current 
alpha cursor location does not change. 

Input 


contrl( 0 ) — 
contrl(1) — 
contrl( 3 ) — 
contrl( 5 ) — 
contrl( 6) — 

Opcode = 5 . 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 10. 

Device handle. 

Output 


contrl(2) -- 
contrl(4) -- 

Number 

Length 

of output vertices = 0. 
of intout array = 0. 


C BINDING 
Procedure Name 

Data Types 


v_eeol( handle ) 

WORD v_eeol ( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Erase to End of Alpha Text Line 


ESCAPE 11: DIRECT 
ALPHA CURSOR 
ADDRESS 

The Direct Alpha Cursor Address escape moves 
the alpha cursor directly to the specified 
row and column address anywhere on the dis¬ 
play surface. Addresses beyond the display- 
able range of the screen are set to the 
nearest value that is within the displayable 
range of the screen. 

Input 

contrl( 0 ) — 
contrl(1) — 
contrl( 3 ) — 
contrl(5) — 
contrl(6) -- 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 2. 
Function id = 11. 

Device handle. 


intin(O) 

intin(l) 

Row number ( 1 to maximum num¬ 
ber of rows ) . 

Column number ( 1 to maximum 
number of columns ) . 

Output 

contrl ( 2) — 
contrl (4) — 

Number of output vertices = 0. 
Length of intout array = 0. 


C BINDING 


Procedure Name vs_curaddress( handle, row, column ) 


Data Types WORD vs_curaddress ( ); 

WORD handle; 

WORD row; 

WORD column; 


Input Arguments handle = contrl[6] 

row = intin[0] 
column = intin[l] 
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Direct Alpha Cursor Address 


ESCAPE 12: OUTPUT 
CURSOR ADDRESSABLE 
ALPHA TEXT 


This escape displays a string of alpha text 
starting at the current cursor position. 
The alpha text attributes currently in effect 
determine alpha text attributes. 


Input contrl( 0 ) 

contrl(1) 
contrl(3) 

contrl(5) 
contrl(6) 

intin 


Opcode = 5. 

Number of input vertices = 0. 
Number of characters in 
character string. 

Function id = 12. 

Device handle. 

Text string in ADE. 


Output 

contrl(2) -- Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 

Procedure Name v_curtext( handle, &string ) 


Data Types WORD v_curtext ( ); 

WORD handle; 

BYTE string[]; 


Input Arguments handle = contrl[6] 

string = intin 

Note: The BYTE values contain the eight 

least significant bits of the intin array. 
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Reverse Video On 


ESCAPE 13: 

REVERSE 

VIDEO ON 

This escape displays all subsequent alpha 
text in reverse video. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(5) — 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 13. 

Device handle. 

Output 

contrl(2) 
contrl(4) -- 

Number of output vertices = 0. 
Length of intout array = 0. 

C BINDING 



Procedure Name 

v_rvon( handle ) 

Data Types 

WORD r_von ( 
WORD handle; 

); 


Input Arguments handle = contrl[6] 
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Reverse Video On 


ESCAPE 14: 

REVERSE 

VIDEO OFF 

This escape displays all subsequent alpha 
C text in normal video format. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) -- 
contrl(5) -- 
contrl(6) -- 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 14. 

Device handle. 

Output 

contrl(2) -- 
contrl(4) -- 

Number 

Length 

of output vertices = 0. 
of intout array = 0. 

C BINDING 




Procedure Name 

v_rvoff( handle ) 


Data Types 

WORD v_rvoff 
WORD handle; 

( ); 



Input Arguments handle = contrl[6] 
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Reverse Video Off 


ESCAPE 15: This escape returns the current position of 

INQUIRE CURRENT the alpha cursor in row, column coordinates. 

ALPHA CURSOR 
ADDRESS 


Input 

contr1(0) — 
contrl(l) — 
contrl(3) -- 
contrl(5) -- 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 15. 

Device handle. 

Output 

contrl(2) -- 

Number of output vertices = 0. 


contrl(4) -- 

Length of intout array = 2. 


intout(O) — 

Row number (1 to the maximum 
number of rows). 


intout(1) — 

Column number (1 to the maxi¬ 
mum number of columns). 


C BINDING 

Procedure Name vq_curaddress( handle, &row, Scolumn ) 


Data Types WORD vq_curaddress ( ); 

WORD handle; 

WORD row; 

WORD handle; 


Input Arguments handle = contrl[6] 

Output Arguments row = intout[0] 

column = intout[1] 
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ESCAPE 16: 

INQUIRE TABLET 
STATUS 

This escape 
of a graphics 

returns the availability status 
tablet. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) -- 
contrl(5) — 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 16. 

Device handle. 

Output 

contrl(2) -- 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 1. 


intout(0) — 

Tablet status. 



0 = tablet not available 

1 = tablet available 


C BINDING 

Procedure Name status = vq_tabstatus( handle ) 


Data Types WORD vq_tabstatus ( ); 

WORD handle; 

WORD status; 


Input Arguments handle = contrl[6] 

Output Arguments status = intout[0] 
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Inquire Tablet Status 


ESCAPE 17: HARO 
COPY 

The device generates a hard copy with this 
escape. The escape is device-specific and 
copies the physical screen to a printer or 
other attached hard copy device. 

Input 

contrl(O) — Opcode = 5. 

contrl(l) -- Number of input vertices = 0. 

contrl(3) — Length of intin array = 0. 

contrl(5) — Function id = 17. 

contrl(6) -- Device handle. 

Output 

contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 

C BINDING 

Procedure Name 

v_hardcopy( handle ) 

Data Types 

WORD v_hardcopy ( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Hard Copy 


ESCAPE 18: PLACE This escape places a graphic cursor at the 
GRAPHIC CURSOR specified location. The cursor is usually a 
AT LOCATION cross hair cursor and is of the same type as 

that used for Input Locator, Request Mode. 
If sample mode input is supported, the ap¬ 
plication can use this call to generate the 
cursor for Input Locator, Sample Mode. In 
memory-mapped devices, the cursor is drawn in 
XOR mode so GEM VDI can remove it. 


Input contrl( 0 ) 

contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

ptsin(0) 


ptsin(1) 


Opcode = 5. 

Number of input vertices = 1. 
Length of intin array = 0. 
Function id = 18. 

Device handle. 

x-coordinate of location to 
place cursor in current coor¬ 
dinate system. 

y-coordinate of location to 
place cursor in current coor¬ 
dinate system. 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 


C BINDING 
Procedure Name 


v_dspcur( handle, x, y ) 


Data Types 


WORD v_dspcur ( ); 

WORD handle; 

WORD x, y; 


Input Arguments 


handle = contrl[6] 
x = ptsin[0] 
y = ptsin[l] 
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Place Graphic Cursor at Location 


ESCAPE 19: REMOVE This escape removes the last graphic cursor 
LAST GRAPHIC placed on the screen. 

CURSOR 


Input 


contrl(O) — Opcode = 5. 

contr1(1) — Number of input vertices = 0. 

contrl(3) — Length of intin array = 0. 

contrl(5) — Function id = 19. 

contrl(6) — Device handle. 


Output 


contrl(2) -- Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 


C BINDING 

Procedure Name vrmcur( handle ) 

Data Types WORD v_rmcur ( ); 

WORD handle; 

Input Arguments handle = contr1[6] 
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Form Advance 


ESCAPE 20: FORM 
ADVANCE 

This escape is required only for printers. 
It advances the printer page. This escape 
can be used instead of invoking a Clear 
Workstation function if it is desirable to 
retain the current printer display list while 
advancing to the next page. 

Input 

contrl(O) -- 
contrl(l) -- 
contrl(3) — 
contrl(5) — 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 20. 

Device handle. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 


C BINDING 

Procedure Name v_form_adv( handle ) 

Data Types WORD v_form_adv( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Output Window 


ESCAPE 21: OUTPUT This escape is required only for printers. 

WINDOW It allows the application to request that a 

particular rectangular window of the picture 
be output to the printer. This escape is 
similar to the Update Workstation function, 
except that the rectangular area must be 
specified. 

Note that use of this function does not al¬ 
ways guarantee that adjacent pictures will 
abut. Pictures will abut with a resolution 
of one printer head height. 


Input contrl( 0 ) 

contr1(1) 
contrl(3) 
contrl(5) 
contrl(6) 

ptsin(O) 

ptsin(1) 

ptsin(2) 


ptsin(3) 


Opcode =5. 

Number of input vertices = 2. 
Length of intin array = 0. 
Function id = 21. 

Device handle. 

x-coordinate of corner of win¬ 
dow to be output in NDC/RC. 
y-coordinate of corner of win¬ 
dow to be output in NDC/RC. 
x-coordinate of corner of win¬ 
dow, diagonally opposite 
corner selected in ptsin(O), 
in NDC/RC. 

y-coordinate of corner of win¬ 
dow, diagonally opposite 
corner selected in ptsin(1), 
in NDC/RC. 


Output 


contrl(2) — Number 
contrl(4) -- Length 


of output vertices = 0. 
of intout array = 0. 
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Output Window 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 


v_output_window( handle. 


WORD v_output_window( ); 
WORD handle; 

WORD xyarray[4]; 


handle = contrl[6] 
xyarray[0] = ptsin[0] 


xyarray[3] = ptsin[3] 


xyarray ) 
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Clear Display List 


ESCAPE 22: CLEAR 
DISPLAY LIST 

This escape is required only for printers. 
It allows the application to request that 
the printer display list be cleared. It is 
similar to the Clear Workstation function, 
but does not cause a form advance on the 
printer. 

Input 

contrl( 0 ) — Opcode = 5. 

contr 1 ( 1 ) — Number of input vertices = 0 . 

contrl(3) -- Length of intin array = 0. 

contrl(5) — Function id = 22. 

contrl(6) -- Device handle. 

Output 

contrl(2) -- Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 

C BINDING 

Procedure Name 

v_clear_disp_list( handle ) 

Data Types 

WORD v_clear_disp list( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Output Bit Image File 


This escape is required only for printers. 
It allows the application to request proces¬ 
sing of a bit image file (see Appendix I, 
"Bit Image File Format"). As input 
parameters, the application provides a 

filename and information on image transfor¬ 

mation and page placement. 

The application uses three parameters to con¬ 
trol image transformation: 

o pixel aspect ratio flag 
o x-axis scaling flag 
o y-axis scaling flag 

The application can set the pixel aspect 
ratio flag to preserve or ignore the pixel 
aspect ratio defined in the bit image file. 
Preserving pixel aspect ratio means the 

printed object will have the same aspect 
ratio it had on the device on which it was 
originally drawn. For example, squares 

remain squares, and circles remain circles. 
Ignoring pixel aspect ratio means the 
printed object will not necessarily have the 
same aspect ratio it had on the original 
device. 

The application can set the two axis scaling 
flags independently of each other. The 
flags determine if the bit image's x or y 
axes are to be scaled fractionally or in in¬ 
teger multiples. The upward boundary of 
this scaling is an application-defined rec¬ 
tangle. 

If an axis of the bit image is scaled frac¬ 
tionally, it will exactly fit the correspon¬ 
ding axis of the scaling rectangle, with the 
exception noted below. 

If an axis of the bit image is scaled in in¬ 
teger multiples, it might not exactly fit 
the corresponding axis of the scaling rec¬ 
tangle. 

If the scaled bit image does not exactly fit 
the scaling rectangle, the application can 
use alignment parameters to locate the bit 
image within the rectangle. These parameters 
allow any combination of three vertical and 
three horizontal positions. 


ESCAPE 23: OUTPUT 
BIT IMAGE FILE 
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Output Bit Image File 


Note: The scaled bit image always resides 
within the scaling rectangle. If a combina¬ 
tion of preserved pixel aspect ratio, 
scaling, or alignment causes the scaled bit 
image to extend beyond an edge of the scaling 
rectangle, GEM VDI clips the bit image to 
that edge. 


Input contr1(0) -- 

contrl(1) — 

contrl(3) — 

contrl(5) -- 
contrl(6) — 

intin(O) 

intin(1) 

intin(2) — 

intin(3) 

intin(4) 

intin(5) — 

intin(n+4)-- 


Opcode = 5. 

Number of input vertices = 2. 

Length of intin array = length 
of filename + 5. 

Function id = 23. 

Device handle. 

Aspect ratio flag. 

0 = ignore aspect ratio 
1 = honor pixel aspect ratio 

Scaling for x-axis. 

0 = fractional scaling 
1 = integer scaling 

Scaling for y-axis. 

0 = fractional scaling 
1 = integer scaling 

Horizontal alignment. 

0 = left 

1 = center 

2 = right 

Vertical alignment. 

0 = top 

1 = middle 

2 = bottom 

First character of filename. 


Last (nth) character of 
filename. 
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Output Bit Image File 


ptsin(O) 

ptsin(l) 

ptsin(2) 

ptsin(3) 

Upper 

Upper 

Lower 

Lower 

left x (if specified), 
left y (if specified), 
right x (if specified), 
right y (if specified). 

Output 

contrl(2) -- 
contrl(4) -- 

Number 

Length 

of output vertices = 0. 
of intout array = 0. 


C BINDING 


Procedure Name v_bit_image( handle, filename, aspect, 

x_scale, y_scale, h_align, 
v_align, xyarray ) 


Data Types WORD v_bit_image ( ) ; 

BYTE filename[]; 

WORD handle, aspect, x_scale, y_scale, 
h_align, v_align; 

WORD xyarray[]; 


Input Arguments handle = contrl[6] 

filename = intin[5] . . . intin[n + 4] 

aspect = intin[0] 

x_scale = intin[l] 

y_scale = intin[2] 

h_align = intin[3] 

v_align = intin[4] 

xyarray[0] = ptsin[0] 

xyarraytl] = ptsinEl] 

xyarray[2] = ptsin[2] 

xyarray[3] = ptsin[3] 


Note: Bytes for the filename array are 
mapped into the corresponding eight least 
significant bits of intin. The string must 
be null-terminated. 
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Output Bit Image File 


ESCAPE 60: SELECT This escape allows the selection of the 
PALETTE palette on the IBM..medium-resolution color 

screen. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

intin(0) 


Opcode = 5. 

Number of input vertices = 0. 
Length of input array = 1. 
Function id = 60. 

Device handle. 

Color selection. 

0 = use red, green, brown 
palette (default) 

1 = use cyan, magenta, white 
palette 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 1. 


intout(O) — Palette selected. 


C BINDING 

Procedure Name selected = vs_palette( handle, palette ) 


Data Types WORD vs_palette( ); 

WORD handle; 

WORD palette; 


Input Arguments handle = contrl[6] 

palette = intin[0] 

Output Arguments selected = intout[0] 
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Polaroid Palette 


POLAROID..PALETTE Use these escapes to modify the operation of 

the Polaroid Palette image recorder. While 
their use is not mandatory, they allow con¬ 
struction of a more efficient user inter¬ 
face. 


Palette Driver These escapes affect a header in the palette 

driver. The header contains information on 
the current state of the driver and the types 
of films it can use. The palette driver con¬ 
tains exposure tables for five film types. 
A 25-character string describes each film 
type, stating its manufacturer and its ASA 
number. These strings are padded with blanks 
if the information requires less than 25 
characters. 

Seventy-two colors are defined for each film 
type. These colors are mapped to an 8 x 9 
array with ASCII capitals (A...H), naming the 
columns and ASCII digits (1...9), numbering 
the rows. A color is selected by its letter 
and number. For example, A2 identifies the 
second color in column A. 

Numbers also identify the port to which the 
palette is connected, an f-stop control, and 
a resolution control for environments where 
memory size prevents the use of the Palet¬ 
te's full capabilities. 

The palette driver normally outputs its mes¬ 
sages directly to the screen. These messages 
include error messages and user prompts. 


Error Messages The palette error messages appear when the 

application calls GEM VDI with a function 
other than Open Workstation, Close Worksta¬ 
tion, or any of the Escape functions. These 
messages can be suppressed with Escape 95. 
The application can then use the code 
returned from Escape 96 to inform the user of 
the error condition. 
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Inquire Palette Film Types 


ESCAPE 91: 

INQUIRE PALETTE 
FILM TYPES 

This escape returns five strings that 
describe the films that the driver is 
currently capable of exposing. The strings 
are padded with spaces if they have fewer 
than 25 characters. The strings are 
returned as ADE integers in intout. 

Input 

contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 91. 

Device handle. 

Output 

contrl(2) 
contrl(4) 

Number of output vertices = 0. 
Length of intout = 125. 


intout 

5 sets of 25 ADE character 
strings. 


C BINDING 


Procedure Name 
Data Types 


Input Arguments 
Output Arguments 


vqp_films( handle, film_names ) 

WORD vqp_films( ); 

WORD handle; 

WORD film_names[125]; 

handle = contrl[6] 

film names = intout 


Note: Intout words (ADE) are converted to 

byte string. 
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Inquire Palette Driver State 


ESCAPE 92: 
INQUIRE PALETTE 
DRIVER STATE 


This escape returns a block of data that 
describes the current state of the driver. 
The state can be updated by changing this 
block and returning it to the driver with 
Escape 93. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 


Opcode = 5. 

Number of input vertices = 0. 
Length of intin = 0. 

Function id = 92. 

Device handle. 


Output contrl(2) -- 

contrl(4) — 

intout(O) -- 

intout(1) — 
intout(2) — 


intout(3) — 


intout(4) — 


intout(5 
to 20) 


Number of output vertices = 0. 
Length of intout array = 20. 

Port number. 

0 = first comm port 

Film number (0...$). 

Lightness control (-3...3). 

Each integer increase 

represents opening the aper¬ 
ture 1/3 of an f-stop. A -3 
results in an exposure half as 
long as normal, while a 3 
doubles the exposure time. 

Interlace flag. 

0 = noninterlaced 
1 = interlaced 

A noninterlaced picture re¬ 
quires slightly more than half 
the memory of an interlaced 
picture. 

Planes, a number (1...4) cor¬ 
responding to number of colors 
(2...16). 

Two-character color codes for 
8-color indices stored in ADE 
format. 
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Inquire Palette Driver State 


C BINDING 
Procedure Name 

Data Types 

Input Arguments 
Output Arguments 


vqp_state( handle, Sport, &film_name. 
Slightness, Sinterlace, Splanes, 
Sindexes ) 


WORD vqp_state( ); 
WORD handle; 

WORD port; 

WORD film_name; 

WORD lightness; 

WORD interlace; 

WORD planes; 

WORD indexes[8][2]; 


handle = contrl[6] 


port = intout[0] 
film_name = intout[1] 
lightness = intout[2] 
interlace = intout[3] 
planes = intout[4] 
indexes = intout[5...20] 
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Set Palette Driver State 


ESCAPE 93: SET 
PALETTE DRIVER 
STATE 


Input 


This escape moves a block of characteristics 
into the driver. Use this function after 
ESCAPE 92. 


contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 


Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 20. 
Function id = 93. 

Device handle. 


intin(0) 


intin(1) 
intin(2) 


intin(3) 


intin(4) 


intin( 5 
to 20) 


Port number. 

0 = first comm port 

Film number (0...4). 

Lightness control (-3...3). 

Each integer indicates opening 
the aperture 1/3 an f-stop. A 
-3 results in an exposure 
half as long as normal, while 
a 3 doubles the exposure time. 

Interlace flag. 

0 = noninterlaced 
1 = interlaced 

Planes (1 to 4), number cor¬ 
responds to number of colors 
(2 to 16). 

Color codes for up to 16 
colors. 
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Set Palette Driver State 


C BINDING 
Procedure Name 

Data Types 


Input Arguments 


vsp_state( handle, port, film_num, 
interlace, planes, indexes ) 


WORD vsp_style( ); 
WORD handle; 

WORD port; 

WORD film_num; 

WORD lightness, 

WORD interlace; 
WORD planes; 

WORD indexes[8][2] ; 


handle = contrl[6] 
port = intin[0] 
film_num = intin[l] 
lightness = intin[2] 
interlace = intin[3] 
planes = intin[4] 
indexes = intin[5-20] 


lightness. 
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Save Palette Driver State 


ESCAPE 94: SAVE 
PALETTE DRIVER 
STATE 

This escape saves the current state of the 
driver to disk. The application can change 
the default film and index mapping with this 
escape. 

Input 

contrl(0) 

__ 

Opcode = 5. 


contrl(1) 

-- 

Number of input vertices = 0. 


contrl(3) 

-- 

Length of intin array = 0. 


contrl(5) 

-- 

Function id = 94. 


contrl(6) 


Device handle. 

Output 

contrl(2) 

__ 

Number of output vertices = 0. 


contrl(4) 


Length of intout array = 0. 


C BINDING 

Procedure Name vsp_save( handle ) 

Data Types WORD vsp_save( ); 

WORD handle; 

Input Arguments handle = contrl[6] 
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Suppress Palette Messages 


ESCAPE 95: 

SUPPRESS PALETTE 
MESSAGES 

This escape allows the application to 
suppress the messages the palette driver 
normally outputs to the screen. These mes¬ 
sages are either error messages or user 
prompts. Refer to Escape 96 for the messages 
and their codes. 

Input 

contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 0. 
Function id = 95. 

Device handle. 

Output 

contrl(2) 
contrl(4) 

Number of output vertices = 0. 
Length of output array = 0. 


C BINDING 

Procedure Name vsp_message( handle ) 

Data Types WORD vsp_message( ); 

WORD handle; 


Input Arguments handle = contrl[6] 
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Palette Error Inquire 



ESCAPE 96: This escape returns an error code so the 
PALETTE ERROR application can notify the user of a problem. 
INQUIRE This escape also returns codes for pending 

user prompts. The error is not cleared, so a 
message can be displayed if such messages 
are not suppressed. 


Input contrl( 0 ) — Opcode = 5 . 

contrl(l) — Number of input vertices = 0. 

contrl(3) — Length of intin array = 0. 

contrl(5) -- Function id = 96. 

contrl(6) — Device handle. 


Output contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 1. 

intout(O) -- Error codes and pending user 
prompts. 

0 = no error 

1 = open dark slide for print 

film 

2 = no port at location 

specified in driver 

3 = palette not found at 

specified port 

4 = video cable disconnected 

5 = operating system does not 

allow memory allocation 

6 = not enough memory to 

allocate buffer 

7 = memory not deallocated 

8 = driver file not found 

9 = driver file found is not 

correct type 

10= prompt user to process 
print film 
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Palette Error Inquire 


C BINDING 

Procedure Name status = vqp_error( handle ) 

Data Types WORD vqp_error( ); 

WORD handle; 


Output Arguments status = intout[0] 
Input Arguments handle = contrl[6] 
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Update Metafile Extents 


ESCAPE 98: UPDATE The values passed in the ptsin array are 
METAFILE EXTENTS used to update the extents information in the 

metafile header. The extents information may 
be used by some applications to provide a 
quick indication of the minimum rectangle 
which will bound all primitives output to the 
metafile. 

If the Update Metafile Extents escape is not 
used when outputting to the metafile, zeroes 
will be written in the extents information 
portion of the metafile header. 


Input contrl( 0 ) 

contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

ptsin(O) 

ptsin(1) 

ptsin(2) 

ptsin(3) 


Opcode = 5. 

Number of input vertices = 2. 
Length of intin array = 0. 
Function id = 98. 

Device handle. 

Minimum x value of the minimum 
bounding rectangle. 

Minimum y value of the minimum 
bounding rectangle. 

Maximum x value of the minimum 
bounding rectangle. 

Maximum y value of the minimum 
bounding rectangle. 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 0. 
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Update Metafile Extents 


C BINDING 

Procedure Name 

Data Types 

Input Arguments 


v_meta_extents(handle, minx, min 
max_x, max_y) 


WORD v_meta_extents(); 

WORD handle, min_x, min_y, max_x. 


handle = contrl[6]; 
min_x = ptsin[0]; 
min_y = ptsin[l]; 
max_x = ptsin[2]; 
max_y = ptsin[3]; 


.Y, 


max_y; 
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Update Metafile Extents 


ESCAPE 99: WRITE The parameters passed in the intin and ptsin 
METAFILE ITEM arrays are written to the metafile with an 

opcode defining the item as a user-defined 
metafile item. Intin(O) should contain a 
sub-opcode that defines what type of user- 
defined metafile item is being written. Sub¬ 
opcodes numbered 0 through 100 are reserved; 
the sub-opcode you use to define your 
metafile item should be numbered 101 or 
higher. 


Input contrl(O) — Opcode = 5. 

contrl(l) -- Number of input vertices. 

contrl(3) — Length of intin array. 

contrl(5) -- Function id = 99. 

contrl(6) -- Device handle. 

intin -- User-defined information. 

intin(O) -- Sub-opcode. 

ptsin — User-defined information. 


Output contr1(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 


Procedure Name v_write_meta(handle, numintin, intin, 

num_ptsin, ptsin) 


Data Types WORD v_write_meta(); 

WORD handle, num_intin, num_ptsin; 

WORD intin[num_intin], ptsin[num_ptsin]; 


Input Arguments handle = contrl[6]; 

num_intin = contrl[3]; 
num_ptsin = contrl[l]; 
intin = intin; 
ptsin = ptsin; 


9-43 



GEM VDI Programmer's Guide 


Change GEM VDI Filename 


ESCAPE 100: 
CHANGE GEM VDI 
FILENAME 


This escape renames a metafile from 
GEMFILE.GEM to the specified name and 
maintains the file extension .GEM. A path 
name and drive can be specified to locate the 
file somewhere other than on the current 
drive and directory. Contrl(3) contains the 
length of the file specification string. 

Note: This escape must be called immediately 
after Open Workstation, or it has no effect. 
It also closes any open metafiles. 


Input 


contrl(0) 
contrl(1) 
contrl(3) 


contrl(5) 
contrl(6) 


Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = number 
of significant characters 
[1...74]. 

Function id = 100. 

Device handle. 


intin( 0 

to n) -- Path/filename. 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


C BINDING 

Procedure Name vm_filename( handle, filename ) 


Data Types WORD vm_filename( ); 

WORD handle; 

BYTE filename[ ]; 


Input Arguments handle = contrl[6] 

filename = intin[0-n] 

Note: The filename must be null-terminated. 


End of Section 9 
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Appendix A 

GEM VDI ERROR MESSAGES 


Command line syntax error 

Description: The GEM VDI command line includes an 

illegal character, path, or drive id. 

Solution: Check for conformance to your operating 

system's conventions for specifying command 
lines. Reenter the command line after correcting 
illegal entries. 


Unable to find ASSIGN.SYS 

Description: This message appears when GEM VDI is 
unable to find the ASSIGN.SYS file in the 
specified location. 

Solution: Locate the ASSIGN.SYS file, checking 
drives and specific directories and subdirec¬ 
tories. Reenter the command with the correct 
location. 


Error reading ASSIGN.SYS 

Description: The format of the ASSIGN.SYS file is 

incorrect. GEM VDI cannot use the file. 

Solution: Refer to Appendix B for the correct 

format for the ASSIGN.SYS file. 


Memory table corrupted 

Description: This message appears when memory is 

corrupted. 

Solution: Reboot your system. 


Insufficient memory 

Description: This message appears when you try to 

reserve memory and not enough memory exists for 
allocation. 

Solution: If your system has adequate memory to 

run GEM VDI, reboot your system. 
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GEM VDI Error Messages 


Invalid memory block address 

Description: This message occurs when the memory 

is corrupted. 

Solution: Reboot the system. 


Drive specification not allowed in ASSIGN.SYS 

Description: This error appears when you specify 
a drive id in the ASSIGN.SYS file, which is 
illegal. 

Solution: Remove the drive id from the file with 
your text editor. Refer to Appendix B for the 
correct format of an ASSIGN.SYS file. 


Illegal device id in ASSIGN.SYS 

Description: This error appears when the device 
id number is greater than 32767 or an alphanumeric 
string, for example 12D4. 

Solution: Refer to Table 1-1 in Section 1 for the 
correct numbers to assign to devices, and correct 
the ASSIGN.SYS file with your text editor. 


Partial record found in ASSIGN.SYS 

Description: This error appears when a partial 

ASSIGN.SYS entry exists. 

Solution: Check your ASSIGN.SYS file for incom¬ 

plete device id numbers or filenames. Refer to 
Appendix B for the correct ASSIGN.SYS file format. 


Invalid filename encountered in ASSIGN.SYS 

Description: This error appears when a filename 

in the ASSIGN.SYS file is too long or contains 
illegal characters. 

Solution: Refer to Appendix B for the ASSIGN.SYS 

file-naming conventions. 
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GEM VDI Error Messages 


Requested path not found 

Description: This message appears when GEM VDI 

does not find the requested path specifying the 
locations of the device drivers. 

Solution: Respecify the path with the correct 

path name. 


ASSIGN.SYS file is empty 

Description: This message appears when GEM VDI 

finds an empty ASSIGN.SYS file. 

Solution: Enter the necessary information with 

your text editor. Refer to Appendix B for the 
necessary ASSIGN.SYS file contents. 


Driver file not found 

Description: GEM VDI cannot find the first driver 

specified in the ASSIGN.SYS file. 

Solution: Make sure that the driver is in the 

specified drive, in the correct directory, and in 
the correct subdirectory. 


Corrupted driver file 

Description: GEM VDI finds the device driver, but 

is unable to use it. 

Solution: Use your distribution disk to make 

another copy of the device driver. Try to use 
the new copy. Contact your dealer if the device 
driver is unusable. 


End of Appendix A 
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Appendix B 
ASSIGN.SYS FILE 


REQUIREMENTS The ASSIGN.SYS file is parsed by the GDOS to 

create the assignment table. The assignment 
table resides in memory and is referenced 
when the application makes an Open Worksta¬ 
tion call. The information required by the 
ASSIGN.SYS includes the device id number and 
the device driver filename and corresponding 
faces. 


Device Id Numbers 


Table B-l. Device Id Numbers 


Type 

Number 

Monitor 

1-10 

Plotter 

11-20 

Printer 

21-30 

Metafile 

31-40 

Camera 

41-50 

Tablet 

51-60 


Device Driver The device driver filenames follow specific 

Filename naming conventions: 

o They must have eight or fewer characters, 
o The first character must be alphabetic, 
o The file extension must be .SYS. 


FORMAT Figure B-l shows the ASSIGN.SYS file format: 

Device Driver Face 

Id Filename Name 

01 SCREEN.SYS FACE1.FNT 

Figure B-l. ASSIGN.SYS File Format 
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Sample ASSIGN.SYS 


SAMPLE ASSIGN.SYS 

21 printer.fnt 
;comments, if desired 
facel.fnt ;facel description 

face2.fnt ;face2 description 

face3.fnt ;face3 description 

01 screen.fnt 
;comments, if desired 
face4.fnt ;face4 description 

face5.fnt ;face5 description 

11 plotter.fnt 
;comments, if desired 
face6.fnt ;face6 description 

face7.fnt ;face7 description 


End of Appendix B 
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Appendix C 

GEM VDI METAFILE FORMAT 


INTRODUCTION 


STANDARD METAFILE 
ITEM FORMAT 


The metafile driver outputs the information 
specified below and performs the described 
operations for the indicated opcodes. 


Most function requests passed to the metafile 
driver result in a standard format metafile 
item being written to the metafile buffer. 
In a standard format metafile item, the con¬ 
trol, integer, and vertex parameters are 
written to the metafile in the following for¬ 
mat: 


word value 


description 


0 

1 

2 

3 

4. . . 
n+4... 


contrl[0] 
contrl[l] 
contrl[3] 
contrl[5] 
ptsin[0-n] 
intin[0-m] 


opcode 

vertex count 
integer parameter count 
sub-opcode (or zero) 
vertices (if provided) 
integer parameters 

(if provided) 


Note that nothing will be output for the 
ptsin or intin information if the vertex 
count or the integer parameter count is zero. 

The following function requests result in the 
output of a standard metafile item: 


3 clear workstation 

4 update workstation 

5, 2 exit alpha mode escape 

5, 3 enter alpha mode escape 
5,21 advance form 

5.21 output window 

5.22 clear display list 

5.23 output bit image file 

6 polyline 

7 polymarker 

8 text 

9 fill area 

11, 1 bar 

11, 2 arc 
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GEM VDI Metafile Format 


NONSTANDARD 
METAFILE ITEMS 

1 open 
workstation 


11, 3 pie 

11, 4 circle 

11, 5 ellipse 

11, 6 elliptical arc 

11, 7 elliptical pie 

11, 8 rounded rectangle 

11, 9 filled rounded rectangle 

11,10 justified graphics text 

12 set character height, absolute mode 

13 set character baseline vector 

14 set color representation 

15 set polyline linetype 

16 set polyline line width 

17 set polyline color index 

18 set polymarker type 

19 set polymarker height 

20 set polymarker color index 

21 set text face 

22 set text color index 

23 set fill interior style 

24 set fill style index 

25 set fill color index 

32 set writing mode 

39 set graphic text alignment 

104 set fill perimeter visibility 

106 set graphic text special effects 

107 set character height, points mode 

108 set polyline end styles 

112 set user-defined fill pattern 

113 set user-defined line style pattern 

114 fill rectangle 

129 set clipping 


The metafile file buffer is initialized and 
the metafile header is output to it. The 
workstation description values normally 
returned by an "open workstation" invocation 
are returned. 
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GEM VDI Metafile Format 


Metafile 

word 

1 

2 

3 

4-7 

8-9 

10 - 13 


header format: 

description 

0 Offffh 

Length of header in words. 

100*major version number + minor 
version number. 

NDC/RC transformation mode flag 

0 = positive y values ascend from 
origin (origin in lower left 
corner) 

2 = positive y values descend 
from origin (origin in upper 
left corner) 

Minimum and maximum x and y ex¬ 
tent values for the information 
contained in the metafile. If 
undefined by the application (see 
"Escape 98: Update Metafile 

Extents"), all four values are 
zero. The values are stored in 
the following order: minimum x, 
minimum y, maximum x, maximum y. 

Physical page size: page width 

in tenths of millimeters, 
followed by page height in tenths 
of millimeters. If undefined by 
the application, both values are 
zero. (See Appendix H, "Reserved 
Metafile Sub-opcodes.") 

The coordinate window which 
defines the coordinate system 
used in the metafile. If un¬ 
defined by the application, all 
four values are zero. The values 
are stored in the following or¬ 
der: lower left x, lower left y, 

upper right x, upper right y. 
(See Appendix H, "Reserved 
Metafile Sub-opcodes.") 
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GEM VDI Metafile Format 


2 close An end-of-metafile opcode is appended to the 

workstation metafile file buffer. The metafile file 

buffer is flushed and the metafile is closed. 


End-of-metafile format: 

word description 

1 Offffh 


SPECIAL METAFILE 
ESCAPES 

5, 98 update 
metafile extents 


5, 99 write 
metafile item 
escape 


The extents information in the metafile 
header is updated to indicate the extents 
passed in the ptsin array. 

A standard format metafile item is written. 
The first word of the intin array should 
contain a sub-opcode that can be used by an 
application to identify the metafile item 
when it is read in. 


5, 100 change GEM If any information currently exists in the 
VDI filename metafile or metafile buffer, the buffer is 
escape flushed and the file is closed. The metafile 

buffer is reinitialized and rudimentary file 
name validation is performed. If the drive, 
path, and filename are valid, they are used 
to update the file control block (FCB) of the 
metafile. The metafile will not actually be 
opened until the first buffer needs to be 
flushed. 
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GEM VDI Metafile Format 


INQUIRY FUNCTIONS 

5, 1 inquire -1 is returned in both INTOUT parameters to 

addressable indicate that cursor addressing is not 

alpha character possible, 

cells escape 

26 inquire color -1 is returned for the color index to 

representation indicate that no value is available. 

35 inquire The set values are returned, 

current polyline 

attributes 

36 inquire 
current polymarker 
attributes 

37 inquire 
current fill 
area attributes 

38 inquire 
current graphic 
text attributes 

102 extended The appropriate inquiry values are returned, 

inquire function 

117 inquire 
character cell 
width 

131 inquire 
current face 
information 


End of Appendix C 


C-5 




Appendix D 
STANDARD KEYBOARD 


GEM VDI defines a standard keyboard so ap¬ 
plications can take advantage of special keys 
not defined in the standard, 7-bit ASCII 
character set. A 16-bit value is used to 
return these characters. The high byte con¬ 
tains a binary value assigned to each key. 
The low byte contains the 7-bit ASCII value, 
if such a value is defined, or a zero if the 
code is an extended code. 


Table D-l. GEM VDI Standard 



Keyboard 

Assignments 

High 

Low 


Byte 

Byte 

Character 

03 

00 

CNTL 2 (Nul 

IE 

01 

CNTL A 

30 

02 

CNTL B 

2E 

03 

CNTL C 

20 

04 

CNTL D 

12 

05 

CNTL E 

21 

06 

CNTL F 

22 

07 

CNTL G 

23 

08 

CNTL H 

17 

09 

CNTL I 

24 

0A 

CNTL J 

25 

0B 

CNTL K 

26 

OC 

CNTL L 

32 

0D 

CNTL M 

31 

0E 

CNTL N 

18 

OF 

CNTL O 

19 

10 

CNTL P 

10 

11 

CNTL Q 

13 

12 

CNTL R 

IF 

13 

CNTL S 

14 

14 

CNTL T 

16 

15 

CNTL U 

2F 

16 

CNTL V 

11 

17 

CNTL W 

2D 

18 

CNTL X 

15 

19 

CNTL Y 

2C 

1A 

CNTL Z 

1A 

IB 

CNTL [ 

2B 

1C 

CNTL \ 

IB 

ID 

CNTL ] 

07 

IE 

CNTL 6 

OC 

IF 

CNTL - 

39 

20 

Space 
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Standard Keyboard 



Table D-l. 

( continued) 

High 

Low 


Byte 

Byte 

Character 

02 

21 

* 

28 

22 

ft 

04 

23 

# 

05 

24 

$ 

06 

25 

% 

08 

26 

& 

28 

27 

f 

0A 

28 

( 

OB 

29 

) 

09 

2A 

* 

OD 

2B 

+ 

33 

2C 

$ 

OC 

2D 

- 

34 

2E 

* 

35 

2F 

/ 

OB 

30 

0 

02 

31 

1 

03 

32 

2 

04 

33 

3 

05 

34 

4 

06 

35 

5 

07 

36 

6 

08 

37 

7 

09 

38 

8 

OA 

39 

9 

27 

3A 

• 

27 

3B 

• 

r 

33 

3C 

< 

OD 

3D 

= 

34 

3E 

> 

35 

3F 

7 

03 

40 

@ 

IE 

41 

A 

30 

42 

B 

2E 

43 

C 

20 

44 

D 

12 

45 

E 

21 

46 

F 

22 

47 

G 

23 

48 

H 

17 

49 

I 

24 

4A 

J 

25 

4B 

K 

26 

4C 

L 

32 

4D 

M 

31 

4E 

N 

18 

4F 

0 
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Standard Keyboard 


Table D-l. (continued) 


High 

Low 

Byte 

Byte 

19 

50 

10 

51 

13 

52 

IF 

53 

14 

54 

16 

55 

2F 

56 

11 

57 

2D 

58 

15 

59 

2C 

5A 

1A 

5B 

2B 

5C 

IB 

5D 

07 

5E 

OC 

5F 

29 

60 

IE 

61 

30 

62 

2E 

63 

20 

64 

12 

65 

21 

66 

22 

67 

23 

68 

17 

69 

24 

6A 

25 

6B 

26 

6C 

32 

6D 

31 

6E 

18 

6F 

19 

70 

10 

71 

13 

72 

IF 

73 

14 

74 

16 

75 

2F 

76 

11 

77 

2D 

78 

15 

79 

2C 

7A 

1A 

7B 

2B 

7C 

IB 

7D 

29 

7E 

0E 

7F 


Character 

P 

Q 

R 

S 

T 

U 

V 
W 
X 

V 
Z 
[ 

\ 

] 

Underscore 

* 

a 

b 

c 

d 

e 

f 

g 

h 

i 

3 

k 

1 

m 

n 

o 

P 

q 

r 

s 

t 

u 

V 

w 

X 

y 

z 


} 

Rubout (DEL) 
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Table D-l. 

(continued 

High 

Low 


Byte 

Byte 

Character 

81 

00 

Alt 0 

78 

00 

Alt 1 

79 

00 

Alt 2 

7A 

00 

Alt 3 

7B 

00 

Alt 4 

7B 

00 

Alt 5 

7D 

00 

Alt 6 

7E 

00 

Alt 7 

7F 

00 

Alt 8 

80 

00 

Alt 9 

IE 

00 

Alt A 

30 

00 

Alt B 

2E 

00 

Alt C 

20 

00 

Alt D 

12 

00 

Alt E 

21 

00 

Alt F 

22 

00 

Alt G 

23 

00 

Alt H 

17 

00 

Alt I 

24 

00 

Alt J 

25 

00 

Alt K 

26 

00 

Alt L 

32 

00 

Alt M 

31 

00 

Alt N 

18 

00 

Alt 0 

19 

00 

Alt P 

10 

00 

Alt Q 

13 

00 

Alt R 

IF 

00 

Alt S 

14 

00 

Alt T 

16 

00 

Alt U 

2F 

00 

Alt V 

11 

00 

Alt W 

2D 

00 

Alt X 

15 

00 

Alt Y 

2C 

00 

Alt Z 

3B 

00 

FI 

3C 

00 

F2 

3D 

00 

F3 

3E 

00 

F4 

3F 

00 

F5 

40 

00 

F6 

41 

00 

F7 

42 

00 

F8 

43 

00 

F9 

44 

00 

F10 

54 

00 

Shift FI 
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Standard Keyboard 


Table D-l. (continued) 


High 

Low 

Byte 

Byte 

55 

00 

56 

00 

57 

00 

58 

00 

59 

00 

5A 

00 

5B 

00 

5C 

00 

5D 

00 

60 

00 

61 

00 

62 

00 

63 

00 

64 

00 

65 

00 

66 

00 

67 

00 

68 

00 

69 

00 

6A 

00 

6B 

00 

6C 

00 

6D 

00 

6E 

00 

6F 

00 

70 

00 

71 

00 

72 

00 

73 

00 

4D 

00 

4D 

36 

74 

00 

50 

00 

50 

32 

48 

00 

48 

38 

77 

00 


Character 

Shift 

F2 

Shift 

F3 

Shift 

F4 

Shift 

F5 

Shift 

F6 

Shift 

F7 

Shift 

F8 

Shift 

F9 

Shift 

F10 

ISO 


Undo 


Help 



( (keypad) 

) (keypad) 

/ (keypad) 

* (keypad) 

7 (keypad) 

8 (keypad) 

9 (keypad) 

4 (keypad) 

5 (keypad) 

6 (keypad) 

1 (keypad) 

2 (keypad) 

3 (keypad) 

0 (keypad) 

. (keypad) 

ENTER (keypad) 
Ctrl left-arrow 
right-arrow 
Shift right-arrow 
Ctrl right-arrow 
down-arrow 
Shift down-arrow 
up-arrow 

Shift up-arrow 
Ctrl Home 
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Standard Keyboard 


Table D-l. 


High 

Low 

Byte 

Byte 

47 

00 

47 

37 

52 

00 

52 

30 

53 

00 

01 

IB 

0E 

08 

82 

00 

83 

00 

1C 

0D 

1C 

0A 

4A 

2B 

4E 

2B 

OF 

09 

OF 

00 

4B 

00 

4B 

34 


End of Appendix D 


(continued) 


Character 

Home 

Shift Home 
Insert 

Shift Insert 

Delete 

Escape 

Backspace 

Alt - 

Alt = 

CR 

Ctrl CR 
Num Pad - 
Num Pad + 

Tab 

Backtab 
left-arrow 
Shift left-arrow 
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Appendix E 

PROCESSOR-SPECIFIC DATA 


68000-SPECIFIC DATA 

Registers and The address of the Parameter Block is passed 

Interrupts in one 32-bit register , DO.1 for 68K from 

the application program to GEM VDI. Dl.w con¬ 
tains the function code 115. 

For CP/M-68K, GEM VDI is invoked via TRAP 2. 
For other 68K operating systems that support 
GEM VDI , the TRAP is identified in the 
operating system's manual. 


Exchange Mouse For 68000-based microcomputers, the appli- 
Movement Vector cation-dependent code is invoked via a JUMP TO 

SUBROUTINE (JSR) instruction. On entry, the 
DO.w register contains the new x position of 
the mouse. The Dl.w register contains the 
new y position of the mouse. When complete, 
the application-dependent code should do a 
RETURN FROM SUBROUTINE (RTS) instruction with 
the x,y position of the mouse the driver is 
to store in DO.w, Dl.w. 


Exchange Button For 68000-based processors, the application 
Change Vector code is invoked via a JUMP TO SUBROUTINE 

(JSR) instruction with DO.w containing the 
mouse button keys. Keys are encoded by the 
same rules that apply to the Sample Mouse 
Button State function. When complete, the 
the application-dependent code do a RETURN 
FROM SUBROUTINE (RTS) instruction with the 
mouse button state the driver should store in 
DO.w. 
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Exchange Cursor 
Change Vector 


Exchange Timer 
Interrupt Vector 


For 68000-based machines, the application- 
dependent code is invoked with a JUMP TO 
SUBROUTINE (JSR) instruction. Upon entry, 
the DO.w register contains the x position and 
the Dl.w register the y position. If the 
application-dependent code does not draw its 
own cursor, a JUMP TO SUBROUTINE (JSR) in¬ 
struction should be performed to the address 
returned in contrl(9) and contrl(lO) with the 
x,y position at which to draw the cursor in 
DO.w and Dl.w. This causes GEM VDI to draw a 
cursor. When complete, the application 
should perform a RETURN FROM SUBROUTINE 
(RTS) instruction. 


For 68000-based processors, the application- 
dependent code is invoked with a JUMP TO 
SUBROUTINE (JSR) instruction. When complete, 
the application should perform a RETURN FROM 
SUBROUTINE (RTS) instruction. 


End of Appendix E 



Appendix F 
CHARACTER SETS 


The 8x8 system font provided with the GEM 
VDI is illustrated in Figure F-l. Not shown 
are the 6 x 6 and 8 x 16 with equivalent 
characters. 

Note that external fonts (those which are 
dynamically loaded) do not include characters 
for decimal equivalents 0 through 31. 
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Character Sets 



Figure F-l. GEM VDI 8x8 Character Set 


End of Appendix F 
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Appendix G 
FONT FORMAT 


INTRODUCTION 

The system fonts and external fonts used in 
GEM VDI are composed of four parts: the font 
data, a font header, a character offset 
table, and a horizontal offset table. 

FONT DATA 

The font data is organized as a single raster 
area. The area's height equals the font 
height and its width equals the sum of the 
character widths. 


The top scan line of the first character in 
the font is aligned to a byte boundary. The 
top scan line of the second character is 
abutted to the first character and is not 
necessarily byte-aligned. That is, the end 
of any character and the beginning of the 
following character often occur within the 
same byte; no byte alignment occurs within 
the font form. 


Bit padding occurs only at the end of a scan 
line. Each scan line in the font form 
begins on a word boundary. The number of 
bytes from the beginning of one scan line to 
the beginning of the next is called the form 
width. The number of scan lines required to 
draw any character is called the form height. 


A flag within the font header indicates the 
orientation of bytes within a word in the 
font data. If the flag is cleared, the font 
data is in a format such that the low byte of 
a word occurs in memory before the high byte 
(Intel..format). If the flag is set, the 
high byte precedes the low byte in memory. 


FONT HEADER The font header contains information that 

describes global aspects of the font. For 
example, the name of the face, the font size, 
the minimum and maximum characters in the 
font, and any other data that applies to 
every character of the font are global 
aspects of that font. The format of the font 
header is shown in Table G-l. 
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Font Header 


Table G-l. Font Header Format 


Byte Number 


Description 


0-1 

2-3 

4-35 


36 - 37 

38 - 39 

40 - 41 
42 - 43 
44 - 45 
46 - 47 
48 - 49 
50 - 51 

52 - 53 

54 - 55 


56 - 57 


58 - 59 


60 - 61 


face identifier (see the 
Set Text Face function) 

font size in points 

face name (see the Inquire 
Face Name and Index func¬ 
tion) 

lowest ADE value in the 
face 

highest ADE value in the 
face 

*top line distance 

*ascent line distance 

*half line distance 

♦descent line distance 

♦bottom line distance 

width of the widest charac¬ 
ter in the font 

width of the widest charac¬ 
ter cell in the face 

left offset (see the 
Inquire Current Face Infor¬ 
mation function) 

right offset (see the 
Inquire Current Face Infor¬ 
mation function) 

thickening: the number of 

pixels by which to widen 
thickened characters 

underline size: the width 

(in pixels) of the under¬ 
line 
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Font Header 


Table G-l. (continued) 

Byte Number Description 

62 - 63 lightening mask: the mask 

used to drop pixels out 
when lightening; usually 
5555H 

64-65 skewing mask: the mask 

that is rotated to deter¬ 
mine when to perform addi¬ 
tional rotation on the 
character to perform 

skewing; usually 5555H 

66 - 67 flags: 

bit 0 set if default sys¬ 
tem font 

bit 1 set if horizontal 

offset tables 

should be used 

bit 2 byte-swap flag (see 
"Font Data") 

bit 3 set if mono-spaced 

font 


68 

- 71 

pointer to the horizontal 
offset table 

72 

- 75 

pointer to the character 
offset table 

76 

- 79 

pointer to the font data 

80 

- 81 

form width (see "Font 

Data" ) 

82 

- 83 

form height (see "Font 

Data") 

84 

- 87 

pointer to the next font 
(set by the driver) 


* - Distances are measured relative to the 
character baseline and are always a positive 
value (magnitude rather than offset). 
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Character Offset Table 


CHARACTER OFFSET 
TABLE 


HORIZONTAL OFFSET 
TABLE 


The character offset table is used to index 
into the font data and to determine the width 
of specific characters in the font. It is 
indexed by relative character value (the ADE 
value of the desired character, minus the 
lowest ADE value in the font) and yields the 
offset from the base of the font data to the 
beginning of the character definition. The 
difference between the offset to a character 
and the offset to the following character 
gives the width of the character. Note that 
the character offset table includes one more 
entry than the number of characters in the 
font so that a width may be obtained for the 
final character in the font. 

Note: The character offset table is required 
even for mono-spaced fonts. 


The horizontal offset table is indexed by 
relative character value and yields any addi¬ 
tional positive or negative spacing necessary 
before outputting the character. The 
horizontal offset table often does not exist. 
Whether it exists or not is indicated by the 
horizontal offset table bit in the flags word 
of the font header. 


End of Appendix G 
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Reserved Metafile Sub-opcodes 


METAFILE SUB- The following sub-opcodes are reserved for 

OPCODES FOR USE use by the GEM Output application. GEM VDI 

WITH GEM OUTPUT defines sub-opcodes for the following sub¬ 

functions : 

o Physical Page Size 
o Coordinate Window 

The opcodes are used by the GEM Output ap¬ 
plication to define how large a picture is to 
be rendered on the output page and also to 
define a transformation which maps from the 
metafile coordinate system to the output 
device. 

The two GEM Output metafile sub-opcodes 
result in an update of the metafile header. 
The opcodes are not actually written to the 
body of the metafile. 


PHYSICAL PAGE SIZE This sub-function defines the size of the 

area to be output to. All of the data in the 
coordinate window is mapped to this area. If 
no physical page size is defined, the Output 
application will attempt a best fit on the 
target device, assuming that "pixels" in the 
metafile are square. 


Input contrl( 0 ) 

contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

intin(0) 
intin(1) 

intin(2) 


Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 3. 
Function id = 99. 

Device handle. 

Sub-opcode number = 0. 

Page width in tenths of 

millimeter. 

Page height in tenths of 

millimeter. 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) -- Length of intout array = 0. 
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COORDINATE WINDOW This sub-function defines the coordinate sys¬ 
tem used in the metafile. All of the data in 
the defined coordinate window is mapped to 
the area defined by the physical page size 
sub-function. 

The coordinate window defaults to NDC space 
(0 to 32K). The location of the origin, (0, 
0), depends on the coordinate space set when 
the metafile was opened (see "Open Worksta¬ 
tion"). For example, if the Open Worksta¬ 
tion function was invoked specifying raster 
coordinate space, the origin would be located 
in the upper left corner of the display sur¬ 
face. 

Note that the window corner information must 
be specified as the lower left and upper 
right corners. Arbitrary opposing corners 
will not convey enough information. 


Input contrl(0) 

contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

intin(0) 
intin(1) 

intin(2) 

intin(3) 

intin(4) 


Opcode = 5. 

Number of input vertices =0. 
Length of intin array = 5. 
Function id = 99. 

Device handle. 

Sub-opcode = 1. 

x-coordinate of lower left 
corner of window, 
y-coordinate of lower left 
corner of window, 
x-coordinate of upper right 
corner of window, 
y-coordinate of upper right 
corner of window. 


Output 


contrl(2) — Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 
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Coordinate Window 


METAFILE SUB¬ 
OPCODES FOR USE 
WITH GEM DRAW 


The following sub-opcodes are reserved for 
use by the GEM Draw..application. GEM VDI 
defines the sub-opcodes for the following 
sub-functions: 


o Start Group 
o End Group 

o Set Attribute Shadow On 
o Set Attribute Shadow Off 
o Start Draw Area Type Primitive 
o End Draw Area Type Primitive 
o Set No Line Style 


START GROUP This sub-function indicated the beginning of 

a group of primitives for the GEM Draw ap¬ 
plication. All subsequent primitives which 
occur before the next End Group sub-opcode 
will be regarded as a group by the GEM Draw 
application. 


Input contrl(0) 

contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

intin(0) 


Opcode = 5. 

Number of input vertices = 0 
Length of intin array = 1. 
Function id = 99. 

Device handle. 

Sub-opcode number = 10. 


Output 


contrl(2) 
contrl(4) 


Number of output vertices = 0. 
Length of intout array = 0. 
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Metafile Sub-opcodes with GEM Draw 


END GROUP 

This sub-function indicated the end of a 
group of primitives for the GEM Draw applica¬ 
tion. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(5) — 
contrl(6) — 

intin(O) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 1. 
Function id = 99. 

Device handle. 

Sub-opcode number = 11. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 

SET NO LINE STYLE 

This sub-function is used by GEM Draw to in¬ 
dicate that subsequent area type primitives 
are not to be outlined. The effects of this 
sub-opcode are cancelled by any subsequent 
set line style opcode. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(5) — 
contrl(6) — 

intin(0) 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 1. 
Function id = 99. 

Device handle. 

Sub-opcode number = 49. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 
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End Group 


This sub-function is used by GEM Draw to 
indicate that all subsequent primitives which 
occur before the next Set Attribute Shadow 
Off sub-opcode should be ignored because they 
are used to draw a drop shadow for the first 
primitive immediately following the Set 
Attribute Shadow Off sub-opcode. Internally, 
GEM Draw assigns a shadowed attribute to the 
first primitive following the Set Attribute 
Shadow Off sub-opcode and performs its own 
shadow drawing. All attribute information 
which occurs between Set Attribute Shadow On 
and Set Attribute Shadow Off will continue to 
be processed. 

Note that GEM Draw will not drop shadows from 
text or from polylines consisting of only two 
vertices. 


Input 

contrl(0) 
contrl(1) 
contrl(3) 
contrl(5) 
contrl(6) 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 1. 
Function id = 99. 

Device handle. 


intin(O) 

Sub-opcode number = 50. 

Output 

contrl(2) 
contrl(4) 

Number of output vertices = 0. 
Length of intout array = 0. 
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Set Attribute Shadow On 


SET ATTRIBUTE 
SHADOW OFF 

This sub-function indicates to GEM Draw the 
end of primitives used to draw a drop shadow 
of the first primitive following this sub-op¬ 
code . 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(5) — 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 1. 
Function id = 99. 

Device handle. 


intin(O) — 

Sub-opcode number = 51. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 

START DRAW AREA 
TYPE PRIMITIVE 

This sub-function indicates to GEM Draw that 
an area type primitive block follows. GEM 
Draw will use the vertices of the first 
primitive (anything except text) which 
follows this sub-opcode to define a GEM Draw 
area type primitive. All other primitives 
encountered before the next End Draw Area 
Type Primitive sub-opcode will be ignored. 

Input 

contrl(0) — 
contrl(1) — 
contrl(3) — 
contrl(5) -- 
contrl(6) — 

Opcode = 5. 

Number of input vertices = 0. 
Length of intin array = 1. 
Function id = 99. 

Device handle. 


intin(0) — 

Sub-opcode number = 80. 

Output 

contrl(2) — 
contrl(4) — 

Number of output vertices = 0. 
Length of intout array = 0. 
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Set Attribute Shadow Off 


END DRAW AREA This sub-function indicates to GEM Draw the 

TYPE PRIMITIVE end of an area type primitive block. 


Input contrl(O) -- Opcode = 5. 

contrl(l) — Number of input vertices = 0. 

contrl(3) -- Length of intin array = 1. 

contrl(5) -- Function id = 99. 

contrl(6) — Device handle. 

intin(O) -- Sub-opcode number = 81. 


Output contrl(2) -- Number of output vertices = 0. 

contrl(4) — Length of intout array = 0. 


End of Appendix H 
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Bit Image File Format 


INTRODUCTION A GEM VDI bit image file contains information 

that can be used to recreate a picture from 
its bit (pixel) image. The file consists of 
a header and raw pixel information. The 
pixel information can be encoded in a 
variety of formats. 


HEADER FORMAT The bit image file header consists eight 16- 

bit words in which the high order byte 
precedes the low order byte. The header 
words are defined as listed in Table G-l. 


Word Contents 

0 Image file version number 

1 Header length in words 

2 Number of planes 

(source device bits per pixel) 

3 Pattern definition length 
(number of bytes) 

4 Source device pixel width (microns) 

5 Source device pixel height (microns) 

6 Scan line width (pixel) 

7 Number of scan line items 


Word one indicates how long the header is. 
Always check this value; future releases 
of GEM might have a longer header. 

Word 3 defines the number of bytes used to 
describe pattern-run (pattern-run is 
described below). The value can range from 
1 to 8. Note that this value is 2 for most 
bit image files taken from screen devices. 


DATA FORMAT The bit image data is composed of a series of 

scan line items. Word 7 in the file header 
indicates how many scan line items are 
present. 

Each scan line item has two components: 

* a vertical replication count 
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Data Format 


* a vertical replication count 

* encoded data for each plane 

The vertical replication count is a word value 
formatted as follows: 


Byte Contents 

0 NUL 

1 NUL 

2 FF Hex 

3 Count 


The count indicates how many identical scan 
lines are defined in this scan-line item. 


The encoded data for each color plane 
follows the vertical replication count. 
The data is presented in the following order: 


first plane--red 
second plane—green 
third plane—blue 
fourth plane—grey 

Data is always provided for all defined bit 
planes. 

Note: The number of pixels described for each 
bit plane of a scan line is not neces¬ 
sarily the scan line width specified in 
the file header. Because the data is en¬ 
coded in byte-wide packets (groups of 
eight pixels), the number of pixels actually 
described is always a multiple of eight and 
is never more than seven pixels wider than 
the scan line width. 


Plane data is encoded in one of three modes: 
solid run, pattern run, or bit string. 

A solid-run item contains a single byte that 
describes a state and the number of bytes 
for which that state is true. The high- or¬ 
der bit defines the state where: 


1 = pixels on 
0 = pixels off 

The low order seven bits define the run 
length. For example, to set a stream of 24 
pixels (3 bytes) on, the encoded data is 83H. 
Similarly, to set a stream of 256 pixels (32 
bytes) off, the encoded data is 20H. 


1-2 



GEM VDI Programmer's Guide 


Data Format 


A pattern-run item describes a set of pat¬ 
tern bytes and the number of times the pat¬ 
tern bytes should be repeated. The number of 
bytes in a pattern is defined in the bit im¬ 
age file header; typically, it is two for a 
screen device image. A pattern-run item is 
defined as follows: 

Byte Contents 

0 NUL 

1 Length of run 

2 First byte of pattern 

n Last byte of pattern 

(n is defined by header 
word 3) 

For example, a stream of 48 pixels (6 bytes) 
alternating red and blue with a pattern 
width of two is encoded as follows: 

* Red plane item (hex values): 00 03 AA AA 

* Blue plane item (hex values): 00 03 55 55 

* Green plane item: The green bit plane 
in this example is a solid run so the 
encoded data is 06H (all pixels are off). 

If a stream of pixels for a given plane can¬ 
not be encoded efficiently as a solid run or 
pattern run, it should be encoded as a bit¬ 
string. A bit-string item is defined as 
follows: 

Byte 

0 
1 
2 


n 


Contents 

80 Hex 
Byte Count 

First byte of bit string 


Last byte of bit string 


End of Appendix I 
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GDOS An Introduction 


HOW TO USE GDOS GDOS is used to provide the application with 

an environment for loading and unloading 
fonts and drivers. GDOS reads in the as¬ 
sign, sys file at boot time and associates 
the fontnames found in the file with a device 
driver and id number. Once the association 
is made, an application can open a physical 
or virtual workstation with an appropriate 
device id and load in the fonts corresponding 
to that id via the vst_load_font call. (The 
driver is loaded at open physical workstation 
time.) 

Making an open physical workstation call will 
install the new workstation in a table of 
open workstations. Workstations have dif¬ 
ferent device id's (e.g. Olp screen.sys). By 
GDOS conventions: 


device type 


device id #'s 


screen driver (VDI) 01-10 
plotter 11-20 
printer 21-30 
metafile 31-40 
camera 41-50 
tablet 51-60 


Open physical workstation looks into each 
entry in the assign.sys information structure 
for the device id. This is passed in in- 
tin[0]. If found a new entry is created in 
the open workstation table {max 16}, other¬ 
wise the handle in control[6] is set to zero 
indicating that the device id was not found. 

NOTE: You may only have one physical 
workstation opened to the screen. But multi¬ 
ple physical workstations can be opened to 
other devices. 

A physical workstation must be opened in or¬ 
der to have access to its particular driver. 
In the case of the screen, a graf_handle call 
will return the currently opened AES physical 
workstation handle. 
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Introduction 


An application can use this physical handle 
to open virtual workstations. For other 
drivers the application must open the physi¬ 
cal device before the application can use it. 
For example: 


intin[0] = 21; 

/* device id for printer */ 
/* see note */ 

for(i=l; i<10; i++) intin[i] = 1; 

/* init intin array */ 

intin[10] =2; /* using raster coords. */ 

v_opnwk(&intin[0],&print_handle,&intout[0]); 

/* physical workstation */ 


Once the physical workstation is opened the 
application can use this physical handle or 
open other virtual workstations to this 
physica1 handle. 

Note: See the example of the as¬ 
sign, sys file for device id 21. 


THE DEFAULT DEVICE In the vdi a device id of 1 is used as 

default. On the ATARI ST this could mean: 


1) high res - if a high resolution 

monitor is attached. 

2) low res - if a color monitor is 

attached. 

N) who knows- future ATARI expansion. 


This is a problem for applications. If a 
physical workstation is opened using a device 
id of 1, the application might get fonts that 
were designed for high resolution on a color 
monitor or vice versa. Therefore, from now 
on device id's of 2, 3 and 4 will correspond 
to low, medium, and high resolution respec¬ 
tively . 
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Opening the default device ID 


01 

default 

02 

low resolution 

03 

medium resolution 

04 

high resolution 

05 

Further ATARI expansion 

06 

07 


08 


09 


10 



************** IMPORTANT NOTE ************** 

The assignments have been made. Applications 
are requested to open virtual workstations 
with device id's of 2, 3, and 4 depending on 
which resolution the ST is currently in. 

If you use the following statement: 

device_id = GetrezO + 2; 

Getrez returns 0.1,2 for low, medium, and 
high resolution. Adding two to it converts it 
to 2,3,4 : The device id's ATARI has as¬ 
signed. 

Now the Atari ST will only need ONE as¬ 
sign, sys file. By placing fonts in the as¬ 
sign, sys file as follows, all applications 
can have access to the proper fonts for each 
resolution. 


Example assign.sys file: 

path = c:\drivers 

Olp screen.sys 
02p screen.sys 
LOWRESl.FNT 
LOWRES2.FNT 
LOWRES3.FNT 
LOWRES4.FNT 
LOWRES5.FNT 
03p screen.sys 
MEDRES1.FNT 
MEDRES2.FNT 
MEDRES3.FNT 
MEDRES4.FNT 
MEDRES5.FNT 
MEDRES6.FNT 


; optional path 
; upper or lower case 
; default 

; LOW res. fonts only 


; MEDIUM res. fonts 
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Opening the default device ID 


04p screen.sys ; HIGH res. fonts 

HIGHRESl.FNT 

HIGHRES2.FNT 

HIGHRES3.FNT 

HIGHRES4.FNT 


SEE open virtual workstation for device id info. 

Note: The aspect ratio for the low and high 
resolution monitors are close enough that 
the fonts for low and high resolution will 
probably be the same. 


VIRTUAL WORKSTATION Question: Since TOS opens a physical 

workstation with a default (1) device id, do 
I have to close the physical station and open 
another one with the proper device id in or¬ 
der to get the fonts for this resolution? 

Answer: NO. Just open a virtual worksta¬ 
tion with the proper device id for the 
resolution the application is currently in. 


Yes device id's are handled a little dif¬ 
ferently for virtual workstations than 
physical ones. When the application opens a 
virtual workstation with a certain device id, 
it is this id that is used to associate the 
driver and fonts with the virtual workstation 
NOT the physical workstation device id. An 
application can therefore find out what 
resolution the Atari ST is in and open the 
proper virtual workstation for that resolu¬ 
tion to obtain the proper fonts. 


ASSIGN.SYS FILE GDOS uses the assign.sys file to determine 

the makeup of the system at boot time. A record 
in the assign.sys file consists of two man¬ 
datory parts: 

1) A workstation id (0-32767). 

2) A name of the driver file associated 
with this id. 
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Assign.sys file 


The workstation id is the id passed to the 
open workstation call in intinLO]. Normally 
it is followed by a space, which serves to 
delimit it from the driver file. However two 
special options are available: 

1) A device id followed by "r" signifies 
that a driver is to be loaded at GDOS 
init time and remain in memory as a 
resident driver. 

2) If the id is followed by a "p" it 
signifies the driver is located per¬ 
manently in ROM. 

3) If none is specified then, default: 
the driver is loaded at open physical 
workstation time. 


Some samples: 

01 fx80.sys ; The driver is loaded only when 
; an open physical workstation 
; is done by the application 
; or the operating system. Used 
; primarily for loading external 

; drivers. 

• 

/ 

Olr temp.sys ; This driver is loaded into RAM 
; at GDOS init time and remains 
; in memory. 

Olp screen.sys ; This driver is located perma- 
; nently in ROM. 


Comments may be included in the assign.sys 
and must begin with ';'. The rest of that 
particular line is ignored. 

The filename must be specified for all 
drivers, although in the case of the rom 
resident driver, it merely satisfies the par¬ 
sing code. If a filename extension is not 
present, it defaults to .sys . 

You may specify in the assign.sys file where 
to find device drivers and font files. This 
is accomplished by the following: 

path = a:\pathname ; This is an example 
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Assign.sys file 


This directive MUST BE THE FIRST NON COMMENT 
LINE in the assign.sys file. If it is not, 
GDOS will use the current path as the 
default. The pathname itself can only be 64 
characters long. If it is longer it will be 
truncated and will not match the path the 
user wants. 

Note: The path specification must be at the 
beginning of the file before any driver/font 
assignment. If not GDOS will install itself 
but the default drive will be the boot drive. 


IS GDOS INSTALLED? You can test to see if GDOS is installed by 

using the following assembly routine: 

move.w #-2,d0 * set dO = -2 

trap #2 * call system 

cmp.w #-2,d0 

beq GDOS_.no t_instal led 


If GDOS is installed dO will be modified and 
therefore will not be a negative two upon 
returning for the trap. 


EXAMPLE ASSIGN.SYS ; This is an example assign.sys file 

path = c:\drivers ; optional path upper or 

; lower case (again this 
; directive must be at the 
; beginning). 

Olp screen.sys ; 01 -workstation id number 

; (01 is default) 

IBMHSS10.FNT ; p -driver permanently 

IBMHSS14.FNT ; loaded at init time. 

IBMHSS18.FNT ; screen.sys -driver name 

IBMHSS36.FNT ; (vdi screen driver). The 

; next four font names are 
; associated with this work_id. 
02p screen.sys ; LOW resolution fonts only 
IBMHSS10.FNT 
IBMHSS14.FNT 
IBMHSS18.FNT 
IBMHSS36.FNT 

03p screen.sys ; MEDIUM res. fonts only 

IBMHSSlO.FNT 

IBMHSS14.FNT 

IBMHSS18.FNT 

IBMHSS36.FNT 
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Example Assign.sys 


04p screen.sys 
IBMHSSlO.FNT 
IBMHSS14.FNT 
IBMHSS18.FNT 
IBMHSS36.FNT 
31 META.SYS 
21 FX80.SYS 
EPSHSS10.FNT 
EPSHSS14.FNT 
EPSHSS20.FNT 
EPSHSS28.FNT 
EPSHSS36.FNT 


HIGH res. fonts only 


meta file driver 

Epson printer driver/fonts 


FONTS The fonts in the GEM VDI are composed of 4 parts: 

the font header, a character offset table, a 
horizontal offset table, and the font data 
itself. The font data is organized as a 
raster image. The top scan line for the first 
character is aligned on a byte boundary. All 
other characters are abutted to the first 
character and may not fall on a byte boun¬ 
dary. Bit padding occurs only at the end of 
a scanline so that the next scan line will 
fall on a word boundary. 

In the font header there are pointers to the 
various tables within the font file. These 
tables are the character offset table, 
horizontal offset table, and the font data. 
With respect to the font file, these pointers 
are actually offsets into the file. GDOS 
adds these offsets to the current location of 
the font when read into memory. 


FONT FILE FORMAT GDOS assumes the font file will be in IBM 

(INTEL) format. All data MUST be byte 
swapped. This is important only for those 
that wish to design their own fonts. 
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Font File Format 


Font header format 

struct font_head { /* describes a font */ 

WORD font_id; /* font id number */ 

WORD point; /* point size of the font */ 

BYTE name[32]; /* 32 bytes of font name */ 

DWORD first_ade; /* ascii value for 1st char in this font */ 

UWORD last_ade; /* ascii value for last char in this font */ 

UWORD top; /* top line distance SEE note */ 

UWORD ascent; /* ascent line distance SEE note */ 

UWORD half; /* half line distance SEE note */ 

UWORD descent; /* descent line distance SEE note */ 

UWORD bottom; /* bottom line distance SEE note */ 

UWORD max_char_width; /* width of the widest char in font */ 

UWORD max_cell_width; /* width of the widest char cell in font*/ 

UWORD lef t__of f set; /* amount character slants left when skewed */ 
UWORD right_offset; /* amount character slants right */ 

UWORD thicken; /* number of pixels to smear */ 

UWORD ul_size; /* size of the underline */ 

UWORD lighten; /* mask to and with to lighten */ 

UWORD skew; /* mask for skewing */ 

UWORD flags; /* font flags */ 

UBYTE *hor_table; /* horizontal offsets */ 

UWORD *off_table; /* character offsets */ 

UWORD *dat_table; /* character definitions */ 

UWORD form_width; /*width in bytes to nxt scanline in bit image*/ 
UWORD form_height; /* number of scan lines in character */ 

struct font_head *next_font;/* pointer to next font */ 

UWORD reserved; /* ATARI reserved flag */ 


NOTE 

. This 


Distances are measured relative to the character baseline 
distance is always a positive magnitude. 
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EXAMPLE FONT TEST CODE 


The following is example code for using GDOS. 
================= FONTST.C ================== 


#include "osbind.h" 
tinclude "define.h" 


#define 

CR 

Oxd 

#define 

LF 

Oxa 

#define 

ON 

1 

#define 

OFF 

0 

#define 

siz_ask 

11 

#define 

siz_rec 

24 

#define 

MSGSIZE 

34 


int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

int 

char 


char 

char 


contrl[12]; /* vdi arrays */ 

intin[256]; 

ptsin[256]; 

intout[256]; 

ptsout[256]; 

scrn_intout[ 256]; /* screen integer out array */ 

vdi_hndl; /* physical screen workstation handle */ 

scrn_hndl; /* virtual screen workstation handle */ 
done; /* done with program flag */ 

num_fonts; /* number of fonts loaded by load font */ 
num_sys_font; /* number of system fonts */ 
charw, charh; /* character height and with */ 
boxw, boxh; /* character cell height and width */ 
xres,yres; /* resolution variables */ 

clip[4]; /* set clipping array */ 

font_index; /* font index returned from vst_name */ 
dev_id; /* virtual workstation device id */ 

point_size; /* pnt. size ret. from vst_point call */ 
prev_psize; /* prev. pnt size from vst_point call */ 
itoa_buff[6]; /* integer to ascii character buffer */ 

/* font message */ 

msg_buff[MSGSIZE] = {"Size asked xxx received xxx 

font\0”}; 

font_name[32]; /* inquire font name array */ 
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main() 

{ 

char ch; /* character *7 

int i,j; /* temp variable */ 

int x,y,yinit; /* scaled text x,y screen printing location */ 

appl_init(); /* start an application */ 

/* get physical screen handle */ 
vdi_hndl=graf_handle(Scharw,Scharh,&boxw,Sboxh); 

do { /* do until we are done */ 

/* the following code will allow the user to see what happens 

* when he opens different virtual workstations with different 

* device id's. This is only an example. Normally the 'C' code 

* in this comment will determine which device id the 

* application should open for the current resolution. 

* 

* dev_id = Getrez() + 2; 

* 

* Use of this code above will maintain software compatability 

* with future Atari computer systems. 

*/ 


dev_id =0; /* init device id to zero */ 

Cconws("\033E"); /* clear screen home cursor */ 


/* which virtual device to open */ 
Cconws("Virtual device number to open (1-9): "); 


/* read in ascii convert to integer */ 
while( ((ch = Cconin()) >= '0') && (ch <= '9') ) { 
dev_id += ((dev_id * 10) + (ch - '0')); 

} 


if(dev_id <= 0) { /* if dev_id = 0 quit */ 

done = TRUE; 
return; 


Cconout(CR); /* move cursor to next line */ 

Cconout(LF); 
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intin[0]=dev_id; /* device id */ 

for (i=l; i<10; ++i) intin[i] = 1; 

/* same information */ 

intin[10] =2; /* using raster coords */ 

scrn_hndl = vdi_hndl; 

v_opnvwk(intin, &scrn_hndl, scrn_intout); 

/* open v work station */ 

xres = scrn_intout[0]; 
yres = scrn_intout[1]; 
num_sys_font = scrn_intout[10]; 

clip[0] = 0; 
clip[l] = 0; 
clip[2] = xres; 
clip[3] = yres; 

vs_clip(scrn_hndl,ON,clip); /* turn on clip */ 


/* load fonts and print workstation info */ 
load_fonts(); 

for(i=l; i<=num_fonts+l; i++) { 

/* select fonts and print */ 

/* inquire font i's name and index*/ 
f ont_index = vqt_name(scrn_hndl,i,font_name); 
f ont_name[15]= 0; 

/* only use first 12 letters */ 

/* set current font */ 
vst_font(scrn_hndl,font_index); 

/* to 'font_index' */ 


Cconws(" \033J" ); /* clear to end of screen */ 

Cconws("FACE : "); 
itoa(i); 

Cconws(itoa_buf f); 

Cconws(" "); 

Cconws(font_name); /* printout font name */ 

Cconout(CR); 

Cconout(LF); 

Cconws("ASKED FOR RECEIVED FONT" ) ; 

Cconout(CR); 

Cconout(LF); 

Cconws ("-”); 

Cconout(CR); 

Cconout(LF); 
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point_size = prev_psize = 999; /* init variables */ 
x = 0; 

y = yinit = 8*7; 

for(j=l; prev_psize>=point_size; j++) { 
prev_psize = point_size; 

prev_psize—; /* next smaller pnt size */ 

itoa(prev_psize); 

strcpy(itoa_buff,&msg_buff[siz_ask]); 

point_size = vst_point(scrn_hndl,prev_psize,&charw, 

&charh,&boxw,Sboxh); 


itoa(point_size); 

strcpy(itoa_buff,&msg_buff[siz_rec]); 


y +=(boxh+2); /* adjustable for next line */ 

if(y>=yres) { /* if going off screen bottom */ 

Cconin(); 

Cconws("\033J”); 
y=yinit+boxh+2; 

} 

v_gtext(scrn_hndl,x,y,msg_buff); /* print msg */ 

} /* font size for loop */ 


CconinC); 

Cconws( "\0331"); 
Cconws( ”\033A"); 
Cconws( "\033A"); 
Cconws( "\033A"); 
} 


/* wait any input */ 
/* erase line */ 

/* move cursor up*/ 
/* move cursor up*/ 
/* move cursor up*/ 
/* font face loop */ 


vst_unload_fonts(scrn_hndl,0); /* unload fonts */ 

v_clsvwk(scrn_hndl); 


} while(!done); 

} /* end main */ 
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/* 

* load the fonts associated with this workstation. 

* print out info on the virtual work station opened 
*/ 


load_fonts() 

{ 

num_fonts = vst_load_fonts(scrn_hndl,0); 

/* load screen fonts */ 

Cconwst"screen handle: "); 

itoa(scrn_hndl); 

Cconws(itoa_buff); 

Cconws(" X ,Y res: "); 
itoa(xres); 

Cconws(itoa_buf f); 

Cconws(” , "); 
itoa(yres); 

Cconws(itoa_buff); 

Cconws(" System text faces:"); 
itoa(num_sys_font); 

Cconws(itoa_buf f); 

Cconout(CR); 

Cconout(LF); 

Cconout(LF); 

Cconws("Number of additional faces available:"); 
itoa(num_fonts); 

Cconws(itoa_buff); 

Cconout(CR); 

Cconout (LF ); 

} 

/* 

* change a 8 bit integer into ascii and store it in itoa_buff 
*/ 
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itoa(num) 


int 

num; 

{ 


int 

numl; 

int 

temp ; 

int 

i-j; 


j~0 ; 

temp = 100; 
for(i=2; i>=0; i--) { 

numl = num / temp; 
itoa_bufftj++] = (numl+'O'); 
num = num - (numl*temp); 
temp /= 10; 

} 

itoa_buff[j] = 0; 

} 


strcpy(s,d) 
char *s, *d; 

{ 

while(*s != 0) { 
*d = *s; 
s++; 
d++; 

} 

} 


END FONTST.C 
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NEW, ADDED FEATURES OF DRIVERS 

1) Pass x-max & y-max resolutions to driver 
- Dot Matrix Only 

This function is meant for wide carriage 
printers. The default x and y resolutions 
are for the narrow carriage printers. 

contrl[l] = 1; Set to ONE! 

ptsin[0] = new x resolution; 

ptsinfl] = new y resolution; 

v_opnwk(intin,&phandle,intout); 

2) Pass a user-defined printer buffer to the 
driver - ALL 

This function allows the program to Malloc() 
its own buffer, perform operations on the 
buffer, and pass the buffer directly to 
v_updwk(). 

contrl[3] =2; 2 parameters 

intin[0] = MSB; Upper Word of Buffer Addr 
intinfl] = LSB; Lower Word of Buffer Addr 
contrl[l] = 1; Don't Clear Raster Buffer 
v_updwk(handle); Make Call 

3) Get the address of the printer buffer - 
SLM804 only 

This function is similar to #2 above, but in 
this case, v_opnwk() returns the address of 
the 1 megabyte raster buffer for the SLM804. 
This function does not work for the dot 
matrix drivers. 

v_opnwk(intin,&phandle,intout); 
contrl[0] =MSB; Upper Word of Buffer Addr 
contrl[l] =LSB; Lower Word of Buffer Addr 

If the driver is the SLM804 driver, the ad¬ 
dress of the buffer will be returned in con- 
trl[0] and contrltl]. Otherwise, 

contrl[0] = 1 and contrl[l] = 0; 

4) Get x and y resolutions from v_opnwk() 
and vq_extnd() 

These functions already exist in v_opnwk() 
and vq_extnd() and is useful for the SLM804. 
The SLM804 utilizes multiple paper sizes. 
(Letter, Legal, A4 and B5). Therefore, the 
returned resolutions can be used to calculate 
the size of the printer buffer required. 
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5) Escape 2000 - SLM804 only 

This function will work only with the SLM804 
driver. Escape 2000 will print out multiple 
copies of the raster buffer at 8 pages per 
minute. Note: 'times' is the number of copies 
in addition to the one that will be printed 
by v_updwk(). For example, if times =5, 6 
copies will be printed. If times = 0, only 1 
copy will be printed. Lastly, this function 
is ignored by the dot matrix drivers. 


contrl[0] = 5; 
contrl[5] = 2000; 
intin[0] = times; 
vdi( ) ; 

v_updwk(phandle); 


6) 

SLM804 Status 

After v_updwk() - SLM804 

only 




After 

performing 

a v_updwk(), intout 10] 

con- 

tains 

the status 

of the laser printer. 

The 

major 

codes a program should be concerned 

about 

are: 



Error 

Code 

STATUS 


0x00 


No Error 


0x02 


Ornery Printer 


0x03 


Toner Empty 


0x05 


Paper Empty 
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Glossary 
ASSIGN.SYS 

coordinate scaling 

coordinate systems 

default device 
driver 

device driver 

device handle 

device 

identification 

number 


Text file created by the driver installation 
program. Associates device identification 
(id) numbers with specific device driver 
files so that devices can be referred to by 
type within the application program. The 
ASSIGN.SYS file can be modified using any 
text editor. 

Converting points from one space or coor¬ 
dinate system to another. In GEM VDI, this 
term refers to the change between Normalized 
Device Coordinates (NDC) and Raster Coor¬ 
dinates (RC). 

Cartesian space in which points are defined. 
GEM VDI supports two systems: Normalized 
Device Coordinates (NDC) and Raster Coor¬ 
dinates (RC). 

First driver named in the ASSIGN.SYS 
file. It must be the largest driver that 
will be loaded during a graphics session. 

Device-dependent portion of GEM VDI that 
translates standard device-independent 
graphics operations to device-specific com¬ 
mand sequences for a particular device. 

Unique value used to identify which worksta¬ 
tion the GEM VDI function should use. GEM 
VDI assigns these numbers at Open Worksta¬ 
tion. 

Id number assigned to a device in the 
ASSIGN.SYS file. Each device in the 
ASSIGN.SYS file has a unique device number 
assigned to it. 
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face 


font 


function code 
graphics command 
graphics device 


Graphics Device 
Operating System 
(GDOS) 


Generalized 

Drawing 

Primitive (GDP) 


Graphics 

Environment Manager 
Virtual Device 
Interface (GEM VDI) 

Graphical Kernel 
System (GKS) 


graphics 

primitives 


Letter style, such as Times Roman. GEM VDI 
stores the definition of each style in a 
data file. When an application calls for the 
use of a particular text face, GEM VDI uses 
the definition to form the text characters on 
the specified graphics device. 

Collection of characters all in one typeface, 
a subset of face. 

See operation code. 

Command that loads the GDOS into memory. 

Hardware that accepts graphics input (mouse 
or keyboard, for example) or displays 
graphics output (screen, printer, or plotter, 
for example). 

Device-independent portion of GEM VDI that 
services graphics requests and calls the 
device driver to send commands to graphics 
devices. 

Display function used to address special 
device capabilities such as curve drawing. 

GEM VDI supports the following GDPs: bar, 
arc, pie, circle, ellipse, elliptical arc, 
elliptical pie, rounded rectangle, filled 
rounded rectangle, and justified graphics 
text. Not all devices support all GDPs. 

Graphics extension to microcomputer opera¬ 
ting systems. The GEM VDI makes it possible 
to run graphics applications on a micro¬ 
computer . 

International standard for the programming 
interface to graphics from an application 
program. 

Basic graphics operations performed by GEM 
VDI, for example, drawing lines, markers, and 
text strings. 
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hot spot 


metafile 


Memory Form 
Definition Block 
(MFDB) 


Normalized Device 
Coordinate (NDC) 
space 


normalized 

device coordinates 

(NDC) 

operation codes 
(opcodes) 


pixel (pixel 
element) 


Area of the cursor that covers the pixel 
whose x,y location is returned during locator 
input. For example, the hot spot on a cross 
hair cursor is the intersection point of the 
two lines making up the cross. 

Data file containing a picture description. 
The GEM VDI metafile can be sent to any 
device or used to exchange a picture between 
two applications. 

Block of memory that defines a raster area. 
An MFDB includes the following raster area 
information: 


o pointer to the memory address of the upper 
left corner of the first plane 

o height and width, in pixels 

o width, in words 

o number of planes 

o flag to indicate if format is standard or 
device-dependent 

o locations reserved for future use 


Uniform virtual space by which a graphics 
application program can pass graphics 
information to a device. The GDOS maps NDCs 
to RCs. NDC space has its origin in the 
lower left corner. 

Any point in NDC space. 


Passed to GDOS as part of a parameter list. 
The opcode indicates which graphics opera¬ 
tion is requested. 

Smallest element of a display surface that 
can be independently referenced. 
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raster area 


Raster 

Coordinate (RC) 
space 


Raster Coordinate 
(RC) 

raster functions 


transformation 

mode 


Virtual Device 
Interface (VDI) 


virtual screen 


Rectangular blocks of either bits in memory 
or pixels on a physical device. Rasters are 
the steps between pixels. 

Actual device units. Raster coordinate space 
has its origin in the upper left corner. Its 
limits are determined by the resolution of 
the specific device. 

Point in RC space. 


Functions that operate on pixels either in¬ 
dividually or in groups. 

Determines which coordinate system the 
application is using, NDC or RC. If NDC, the 
transformation mode determines how the GDOS 
maps the NDCs to the RCs with two methods: 
full NDC to RC space or uniform NDC to RC 
space. 

Standard interface between device-dependent 
and device-independent code in a graphics en¬ 
vironment. The GEM VDI makes all device 
drivers appear identical to the calling 
program. 

Block of memory that can be addressed as if 
it were a memory-mapped display. 


End of Glossary 
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A 

architecture, 1-2 

B 

bit image file format, 1-1 
BYTE, 2-1 

C 

Cell Array function, 4-11 
character offset, G-4 
Close Virtual Screen 

Workstation function, 3-12 
Close Workstation function, 3-9 
control array, 1-5 
coordinate window, H-l, H-2 
Copy Raster 

Opaque function, 6-7 
Transparent function, 6-9 
D 

data format with bit image 
files, 1-1 
device drivers, 1-2 
device handle, 1-4 
device id number, 1-4 

E 

error messages, A-l 
escape 

alpha cursor down, 9-1, 9-8 
alpha cursor home, 9-11 
alpha cursor left, 9-1, 9-10 
alpha cursor right, 9-1, 9-9 
alpha cursor up, 9-1, 9-7 
clear display list, 9-2, 9-26 
direct alpha cursor address, 
9-1, 9-14 

enter alpha mode, 9-1, 9-6 
erase to end of alpha screen, 
9-1, 9-12 

erase to end of alpha text 
line, 9-1, 9-13 
exit alpha mode, 9-1, 9-5 
form advance, 9-2, 9-23 
change GEM VDI filename, 9-44 
hard copy, 9-2, 9-20 
home alpha cursor, 9-1, 9-11 


inquire addressable alpha 
character cells, 9-1, 9-4 
inquire current alpha cursor 
address, 9-2, 9-18 
inquire palette driver 
state, 9-2, 9-33 
inquire palette film 
types, 9-2, 9-32 
inquire tablet status, 

9-2, 9-19 

output bit image file, 9-27 
output cursor addressable 
alpha text, 9-1, 9-15 
output window, 9-2, 9-24 
palette error inquire, 

9-2, 9-39 

place graphic cursor at 
location, 9-2, 9-21 
remove last graphic 
cursor, 9-2, 9-22 
reverse video off, 9-2,9-17 
reverse video on, 9-1, 

9-16 

save palette driver state, 
9-2, 9-37 

select palette, 9-2, 

9-30 

set palette driver state, 

9-2, 9-35 
suppress palette 

messages, 9-2, 9-38 
update metafile extents, 9-41 
write metafile item, 

9-2, 9-43 

Exchange Button Change 

Vector function, 7-27 
Exchange Cursor Change 

Vector function, 7-31 
Exchange Mouse Movement 
Vector function, 7-29 
extended run-length encoding, 
1-2 

external fonts, G-l 

F 

Filled Area function, 4-8 
Filled Rounded Rectangle 
function, 4-25 
font data, G-l 
font form, G-l 
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font format, G-l 
font header, G-l, J-8 
Form Advance 
function, 9-23 
function code 
escape, 9-1 
function 
Bar, 4-8 

Cell Array, 4-11 
Circle, 4-28 
Close Virtual Screen 
Workstation, 3-12 
Close Workstation, 3-9 
Copy Raster, Opaque, 6-7 
Copy Raster, Transparent, 6-9 
Exchange Button Change 
Vector, 7-27 

Exchange Cursor Change Vector 
function, 7-31 
Exchange Mouse Movement 
Vector, 7-30 
Filled Area, 4-8 
Filled Rounded Rectangle, 

4-25 

Get Pixel , 6-13 
Input Locator, Request Mode, 
7-3 

Input Locator, Sample Mode, 
7-6 

Input String, Request Mode, 
7-15 

Input String, Sample Mode, 

7- 17 

Input Valuator, 7-9 
Inquire Current Face 
Information, 8-21 
Inquire Face Name and Index, 

8- 19 

Justified Graphics Text, 4-27 
Load Fonts, 3-15 
Open Virtual Screen 
Workstation, 3-10 
Open Workstation, 3-1 
Polyline, 4-1 
Polymarker , 4-4 
Rounded Rectangle, 4-25 
Sample Keyboard State 
Information, 7-33 
Sample Mouse Button State, 
7-26 

Set Graphic Text Special 
Effects, 5-27 
Set Input Mode, 7-1 
Set Mouse Form, 7-19 


Set Polyline End Styles, 5-12 
Set Text Face, 5-24 
Set User-defined Fill 
Pattern, 5-37 
Text, 4-6 

Unload Fonts, 3-16 
Update Workstation, 3-14 

G 

GDOS, 1-2, J-l 
GDP 

Arc & Pie function, 4-19 
Bar function, 4-18 
Circle function, 4-21 
Ellipse, 4-24 

Elliptical Arc and Pie, 4-22 
GEMVDI command, 2-19 
Get Pixel function, 6-13 
Graphics Device Operating 
System, See GDOS 

H 

hard copy escape, 9-20 
header format with bit image 
files, 1-1 

hide cursor escape, 7-25 
horizontal offset table, G-4 

I 

Input Locator 

Request Mode function, 7-3 
Sample Mode function, 7-6 
input parameters array, 1-5 
input point coordinates, 1-5 
Input String 

Request Mode function, 7-15 
Sample Mode function, 7-17 
Input Valuator function, 7-9 
inquire cell array, 8-23 
inquire character cell width, 
8-17 

inquire color representation, 
8-5 

Inquire Current Face 

Information function, 8-21 
Inquire Face Name and Index 
function, 8-19 

Inquire Palette Driver State 
Escape, 9-33 

Inquire Palette Film Types 
Escape, 9-32 
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inquire text extent, 8-15 
interrupt for 68K, E-l 

J 

justified graphics text, 4-27 

L 

Load Fonts function, 3-15 

M 

memory requirements, 2-20 
metafile sub-opcodes, H-l, H-3 
multiple workstations, 1-4 

N 

NDC, 1-4, 1-6 

normalized device coordinates, 

1- 4, 1-6 

O 

Open Virtual Screen Workstation 
function, 3-10 

Open Workstation function, 3-1 
output parameters, 1-5 
output point parameters, 1-5 
Output Window 
Escape, 9-24 

P 

Palette Error Inquire 
Escape, 9-39 
physical page size, H-l 
plotter functions, 2-13 
Polaroid Palette Escapes, 9-31 . 
Polyline function, 4-1 
Polymarker function, 4-4 

R 

registers for 68K, E-3 
registers for 8086, E-l 
required functions for 
printers, 2-11 

required functions for screens, 

2- 9 

reserved metafile sub-opcodes, 
H-l 


Rounded Rectangle function, 

4- 25 

run-length encoding, 1-1, 1-2 

s 

Sample Keyboard State 

Information function, 7-33 
Sample Mouse Button State 
function, 7-26 
Save Palette Driver State 
Escape, 9-37 
scan line, G-l 
Select Palette 
Escape, 9-30 

set character baseline vector, 

5- 22 

set character cell height 
points mode, 5-18, 5-20 
set character height 
absolute mode, 5-18 
Set Clipping Rectangle 
function, 3-18 

set color representation, 5-4 
set fill color index, 5-35 
set fill interior style, 5-32 
set fill perimeter visibility, 
5-36 

set fill style index, 5-33 
set graphic text alignment, 
5-30 

set graphic text color index, 
5-26 

set graphic text special 
effects, 5-27 

Set Input Mode function, 7-1 
Set Mouse Form function, 7-19 
Set Palette Driver State 
Escape, 9-32 

set polyline color index, 5-11 
Set Polyline End Styles 
function, 5-12 
set polyline line type, 5-6 
set polyline line width, 5-9 
set polymarker color index, 
5-17 

set polymarker height, 5-16 
set polymarker type, 5-14 
set text color index, 5-24 
Set Text Face function, 5-24 
Set User-defined Fill Pattern 
function, 5-33 

set user-defined line style, 
5-8 
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set writing mode, 5-1 
show cursor, 7-23 
stack requirements, 2-20 
sub-opcodes, H-l 
Suppress Palette Messages 
Escape, 9-38 
system fonts, G-l 

T 

Text function, 4-6 
transforming points, 1-6 

D 

Unload fonts function, 3-16 
Update Workstation function, 
3-14 


V 

VDI, 1-5 

Virtual Device Interface, 1-5 
VDI, 1-5 


W 

WORD, 2-1 

Write Metafile Item Escape, 
9-43 
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